@3fn/core 14.1.0 → 15.0.0

package/dist/tools/integrity/Invariants.js

@@ -12,7 +12,7 @@
  *     This is exactly how Finding 1 hid (216 rgba in both committed and fresh).
  *
  *   - P5 (theme-varying rule): the index's `themeVarying` set must be the
- *     dist base-mode set (5 keys), NOT the registry-wide set (10 keys). A future
+ *     dist base-mode set (EXPECTED_BASE_THEME_VARYING), NOT the registry-wide set. A future
  *     "simplification" that pipes the registry-wide Set through to the index would
  *     reproduce identically committed-vs-fresh while silently re-breaking R5.
  *     (§4.1 residual risk, Task 3 completion.)
@@ -77,20 +77,39 @@ exports.SHADOW_COLOR_PRIMITIVES = [
 ];
 /**
  * The base-scoped theme-varying set the INDEX must mark `themeVarying: true`
- * (the 5 dist base-mode dark-override keys). This is the readout the index uses;
- * it is deliberately NOT the registry-wide 10 (which over-includes WCAG-only
+ * (the dist base-mode dark-override keys). This is the readout the index uses;
+ * it is deliberately NOT the registry-wide set (which over-includes WCAG-only
  * contrast keys). See Task 3 completion §"Why two theme-varying sets coexist".
+ *
+ * This list grows when a token gains a genuine base-mode DARK override in
+ * src/tokens/themes/dark/SemanticOverrides.ts — that is the invariant holding, not
+ * breaking. It must NEVER grow by absorbing a WCAG_ONLY_OVERMARKS key; that is the
+ * §4.1 regression the anti-conflation sentinel below names.
+ *
+ * 5 → 6 on 2026-09-12: `color.feedback.success.text` gained a dark override
+ * (green500 → green300) as part of the WCAG AA remediation of the Spec 112
+ * completion-claims audit finding F4. See
+ * .kiro/issues/2026-09-12-spec-112-completion-claims-audit.md § F4.
+ *
+ * 6 → 9 on 2026-09-13: `color.text.default`, `color.text.muted`, and
+ * `color.text.subtle` each gained a dark override (white100/white300/white500) as
+ * part of the interim dark-text-hierarchy fix, Peter-ratified. See
+ * .kiro/issues/2026-09-12-semantic-contrast-adjudication-queue.md.
  */
 exports.EXPECTED_BASE_THEME_VARYING = [
     'color.action.navigation',
     'color.background.primary.subtle',
+    'color.feedback.success.text',
     'color.icon.navigation.inactive',
     'color.structure.border.subtle',
     'color.structure.canvas',
+    'color.text.default',
+    'color.text.muted',
+    'color.text.subtle',
 ];
 /**
- * Sentinel WCAG-only over-marks: keys that the registry-wide set (10) marks but
- * the base-scoped set (5) must NOT. If any of these is `themeVarying: true`, the
+ * Sentinel WCAG-only over-marks: keys that the registry-wide set marks but
+ * the base-scoped set must NOT. If any of these is `themeVarying: true`, the
  * index has been silently re-wired to the registry-wide Set — the §4.1 regression.
  * (This is the anti-conflation guard's negative assertion.)
  */
@@ -165,12 +184,12 @@ function rgbaColorPrimitives(primitivesYaml) {
  * P5 — theme-varying is the base-scoped set, NOT the registry-wide set.
  *
  * Two assertions (both must hold):
- *   (a) the index's `themeVarying: true` set equals EXACTLY the expected 5 base keys
+ *   (a) the index's `themeVarying: true` set equals EXACTLY the expected base keys
  *       (a missing or extra key is a divergence from the dist base-mode set); and
  *   (b) NONE of the known WCAG-only over-marks is `themeVarying: true` — the
  *       anti-conflation guard. (b) is redundant with (a) when (a) holds, but it
  *       is the explicit, named regression sentinel: if a future change pipes the
- *       registry-wide 10 through to the index, (b) names exactly which over-marks
+ *       registry-wide set through to the index, (b) names exactly which over-marks
  *       reappeared, making the §4.1 re-break legible rather than a generic "extra key".
  */
 function assertThemeVaryingBaseScoped(semanticsYaml) {
@@ -180,7 +199,7 @@ function assertThemeVaryingBaseScoped(semanticsYaml) {
         .filter(([, raw]) => raw.themeVarying === true)
         .map(([name]) => name));
     const expected = new Set(exports.EXPECTED_BASE_THEME_VARYING);
-    // (a) exact-set equality with the base-scoped 5.
+    // (a) exact-set equality with the base-scoped set (EXPECTED_BASE_THEME_VARYING).
     for (const key of expected) {
         if (!actualTrue.has(key)) {
             violations.push({

package/dist/tools/integrity/cli/run-audit.js

@@ -104,7 +104,7 @@ rgbaScan('token-index/primitives.yaml');
 rgbaScan('token-index/semantics.yaml');
 oklchVsRgba('dist/DesignTokens.web.css');
 // CHECK 3 (Task 5.1) — the absolute correctness-property assertions the re-diff cannot catch:
-//   P3 (no rgba except the shadow allowlist) and P5 (theme-varying = base-scoped 5, not registry-wide 10).
+//   P3 (no rgba except the shadow allowlist) and P5 (theme-varying = the base-scoped set, not the registry-wide one).
 // Run against the COMMITTED token-index (repo cwd) — these must hold regardless of drift.
 console.log('\n--- CHECK 3: token-index invariants (P3 no-legacy-color, P5 theme-varying-base-scoped) ---\n');
 const primitivesYaml = readMaybe(path.resolve(repo, 'token-index/primitives.yaml'));

package/dist/types/PrimitiveToken.d.ts

@@ -87,7 +87,21 @@ export interface PrimitiveToken {
     description: string;
     /** Mathematical relationship to family base value */
     mathematicalRelationship: string;
-    /** Whether token aligns with 8-unit baseline grid (spacing/radius families) */
+    /**
+     * Whether the token aligns with the 8-unit baseline grid.
+     *
+     * Predicate (system-wide): `true` iff `baseValue` is an exact multiple of 8 AND the
+     * token's family participates in the baseline grid (dimensional families — spacing,
+     * radius, sizing, blur, shadow offset, tap area, font size). Non-participating families
+     * (border width, breakpoint, density, and all non-dimensional families) always carry
+     * `false`, meaning "not applicable".
+     *
+     * Values on the 4-unit subgrid (4, 12, 20) are `false`: valid values, not grid-aligned
+     * ones. Enforcement of the grid itself is narrower than this flag — ErrorValidator and
+     * PassValidator only *require* alignment for spacing and radius.
+     *
+     * Guarded by `src/tokens/__tests__/BaselineGridAlignmentFlag.test.ts`.
+     */
     baselineGridAlignment: boolean;
     /** Whether token is a strategic flexibility exception within its family */
     isStrategicFlexibility: boolean;

package/dist/types/generated/TokenTypes.d.ts

@@ -6,7 +6,7 @@
  *
  * To regenerate: npm run generate:types
  *
- * Generated: 2026-08-26T14:15:23.873Z
+ * Generated: 2026-10-03T02:14:56.799Z
  */
 /**
  * Union type of all semantic color token names

package/dist/types/generated/TokenTypes.js

@@ -7,7 +7,7 @@
  *
  * To regenerate: npm run generate:types
  *
- * Generated: 2026-08-26T14:15:23.873Z
+ * Generated: 2026-10-03T02:14:56.799Z
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isColorTokenName = isColorTokenName;

package/dist/types/index.d.ts

@@ -11,5 +11,6 @@ export { SemanticCategory } from './SemanticToken';
 export type { ValidationResult, UsagePatternResult, ConsistencyValidationResult, ValidationLevel } from './ValidationResult';
 export type { TranslationOutput, UnitConversionConfig, FormatGenerationConfig, PathOrganizationConfig, TargetPlatform, OutputFormat } from './TranslationOutput';
 export type { InsetPadding } from './ComponentTypes';
+export type { Oklch } from '../color/OklchConverter';
 export type { ColorTokenName, OpacityTokenName, ShadowTokenName, } from './generated/TokenTypes';
 //# sourceMappingURL=index.d.ts.map

package/governance/AI-Collaboration-Framework.md

@@ -8,7 +8,7 @@ description: Detailed protocols for AI-human collaboration — mandatory bias mi
 # AI Collaboration Framework
 
 **Date**: 2026-01-15
-**Last Reviewed**: 2026-01-15
+**Last Reviewed**: 2026-09-19
 **Purpose**: Detailed protocols for AI-human collaboration with mandatory bias mitigation and candid communication
 **Organization**: process-standard
 **Scope**: cross-project
@@ -114,23 +114,31 @@ This is a common failure mode: humans ask "What do you think about X?" and AI in
 
 ## Mandatory Devil's Advocate Protocols
 
-### Protocol 1: Counter-Argument Requirement
+### Protocol 1: Counter-Argument Requirement (with the fold-back discipline)
 
-**RULE**: For every significant recommendation, AI agents MUST provide at least one strong counter-argument.
+**RULE**: For every significant recommendation, AI agents MUST provide at least one strong counter-argument — and MUST use it before presenting it *(fold-back discipline, ratified 2026-09-19 — `.kiro/docs/ballots/2026-09-19-counter-argument-fold-back.md`)*:
+
+1. **Fold-back first**: run the counter-argument against your own proposal; fold in what it genuinely improves.
+2. **Present the residual**: give the revised proposal with the **surviving** counter-argument — what revision could not absorb — stated plainly. An empty residual signals the counter-argument was too weak, not that the proposal is safe.
+3. **Surface forks**: where the counter-argument exposes a fork between defensible options, surface the fork; never absorb it by picking — the pick is the human's.
+
+**The guard**: never manufacture an absorbable objection to display a revision. The strongest counter-arguments are the ones that survive revision; the residual is the deliverable, not the absorption.
 
 **Correct:**
-> "I recommend implementing the token system because it provides consistency.
+> "I recommend implementing the token system because it provides consistency. Working my counter-argument against the proposal changed it: I dropped the per-component override layer, which existed only to answer the over-abstraction objection and was itself the main source of it.
 >
-> HOWEVER, here's why this might be wrong:
-> - Token systems can create over-abstraction that slows development
-> - The complexity may not be justified for a small design system
-> - Maintenance overhead could exceed benefits
+> HOWEVER, what survives revision:
+> - The complexity may still not be justified for a small design system
+> - Maintenance overhead could exceed benefits at this team size
 >
-> What's your assessment of these risks?"
+> What's your assessment of these residual risks?"
 
 **Incorrect:**
 > "I recommend implementing the token system because it provides consistency and will solve your problems."
 
+**Also incorrect** (the pre-fold-back form — a counter-argument the proposal never absorbed nor survived is decoration):
+> "I recommend implementing the token system. HOWEVER, here's why this might be wrong: [objections the proposal was never tested against]. What's your assessment?"
+
 ### Protocol 2: Risk-First Analysis
 
 **RULE**: AI agents must lead with risks and limitations before presenting benefits.
@@ -251,7 +259,7 @@ This is not about proving anyone right or wrong. It's about preserving options f
 
 **MANDATORY**: All AI agents must implement these behaviors:
 
-- Provide counter-arguments to significant recommendations
+- Provide counter-arguments to significant recommendations — run each against your own proposal first, and present the surviving residual (the fold-back discipline, Protocol 1)
 - Lead with risks and limitations
 - Challenge human assumptions explicitly
 - Ask for evidence to support claims
@@ -268,6 +276,7 @@ This is not about proving anyone right or wrong. It's about preserving options f
 ### AI Anti-Patterns
 
 - Agree with human without providing counter-arguments
+- Present a counter-argument the proposal was never tested against (compliance theater), or manufacture absorbable objections to display a revision
 - Recommend solutions without identifying risks
 - Use confident language without supporting evidence
 - Focus on benefits while minimizing limitations

package/governance/Component-Family-Navigation.md

@@ -21,11 +21,11 @@ description: Navigation component family — wayfinding and view-switching compo
 
 **Family**: Navigation
 **Shared Need**: Wayfinding and view switching
-**Readiness**: 🟡 Beta (2 components implemented, family hierarchy evolving)
+**Readiness**: 🟡 Beta (5 components implemented, family hierarchy evolving)
 
 ### Purpose
 
-The Navigation family provides components for user wayfinding and switching between views. Implemented components include a segmented control for mutually exclusive content views and a primary bottom tab bar for top-level app destinations.
+The Navigation family provides components for user wayfinding and switching between views. Five components are implemented: a segmented control for mutually exclusive content views, a primary bottom tab bar for top-level app destinations, and three top-of-screen navigation headers (Nav-Header-Base, Nav-Header-Page, Nav-Header-App).
 
 ### Key Characteristics
 

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