@3fn/core 14.1.0 → 15.0.0

package/governance/Product-Handoff-Protocol.md

@@ -8,7 +8,7 @@ description: Structured communication protocol for implementation-phase work bet
 # Product Handoff Protocol
 
 **Date**: 2026-03-20
-**Last Reviewed**: 2026-03-20
+**Last Reviewed**: 2026-09-19
 **Purpose**: Structured communication protocol for implementation-phase work between product agents
 **Organization**: process-standard
 **Scope**: cross-project
@@ -65,9 +65,34 @@ When a Tier 1 clarification results in a design or implementation decision, the
 
 **Frequency**: Once per screen or flow completion
 **Direction**: Platform → Leo
-**Format**: Structured, captured for reference
+**Format**: Structured, **committed**, captured for reference
 **Expectation**: Delivered when implementation is complete, before moving to next work
 
+#### The committed-report convention
+
+**The Implementation Report is committed at `.kiro/specs/<spec>/reports/implementation-<platform>.md`**, on that platform parent's own unit branch, as part of that parent's completion — **traversing the same PR gate as the work it reports.** A report that exists only as a relayed message is not citable, and product-tier Evidence cells must cite something a later reader can open.
+
+**Claim-grain citation.** A product-tier Evidence citation SHALL resolve to **a specific claim inside the report** — a section anchor, or the test or command the report records — **never the report as a whole**. `implementation-ios.md` is not evidence; `implementation-ios.md#navigation-stack` is.
+
+**Spec-revision citation (SHOULD).** A citation SHOULD name **the screen-spec revision it was verified against** — a SHA or a dated revision. *This is a stated reading, not a silent one*: SHOULD is the ruled strength of the advisory that proposed it, the reference-drift mitigation is adopted **now at SHOULD strength AND re-examined at the revisit below**, and SHALL would have been an unruled gain. The reading is on the record precisely so no later reader has to infer whether the softer strength was a decision or an omission.
+
+**Fourth-evidence-kind records.** This convention also homes **visual-direction sign-offs** — cross-platform design-review notes and design-critique records — at no extra cost: committed at the same path family, citable at claim grain, and therefore usable as the fourth Evidence kind (a locatable decision record / approval citation) in a completion doc.
+
+#### NAMED REVISIT — at the first product spec's tasks round
+
+This convention is adopted on system-side evidence and a product-side prediction. **The prediction is revisited, on the record, at the first product spec's tasks round**, against three questions carried verbatim:
+
+> **(i)** is 3× row multiplication livable at the real criterion count — **measured, not estimated**;
+> **(ii)** did the committed-report substrate hold — **locatable, claim-grain, consistently authored across three platform agents**;
+> **(iii)** did platform-set evolution or reference drift force a shape change.
+
+Two answers are fixed in advance so the revisit measures the open questions rather than re-litigating the settled ones:
+
+- **Product specs are `**Criteria mode**: per-parent`.**
+- **A later-added platform is a NEW PARITY PARENT** — not an amendment to a completed parent's criteria set.
+
+**Question (ii) is read to include path collision on a future multi-screen spec**: `reports/implementation-<platform>.md` is unique per spec, not per screen, so a spec covering several screens will need either a screen segment in the filename or a section-per-screen discipline. That is folded into the revisit's net deliberately, rather than pre-designed here on zero instances.
+
 Template:
 
 ```markdown

package/governance/Test-Behavioral-Contract-Validation.md

@@ -306,6 +306,8 @@ error_state_validation_checklist:
 
 **Provenance**: As of the 2026-07-15 adjudication (`.kiro/issues/button-cta-disabled-state-adjudication.md`), the no-disabled-states philosophy holds corpus-wide with **zero exceptions** — Button-CTA was the last component carrying `state_disabled`, and it has been removed. No component in the corpus may declare a disabled state as a behavioral contract, and `blend.disabledDesaturate` (along with the other disabled-state blend wrappers) is deprecated. Validation for this contract type has inverted: rather than validating that a disabled state behaves correctly, validation now confirms a disabled state does **not exist** and cannot be reintroduced.
 
+**Ignore-vs-throw parity (2026-09-19)**: An earlier corpus split — Button-CTA ignoring a consumer-set `disabled` silently vs. Button-VerticalList-Item throwing on it — was ruled (option d): DesignerPunk components SHALL NOT observe, expose, or reject a consumer-set `disabled` input; the input is inert (ignore, never throw). Button-VerticalList-Item's throw was retired to the Button-CTA guard shape below. The checklist that follows already taught the ruled mechanism throughout — it was Button-VerticalList-Item's implementation that contradicted it, not this document. See `.kiro/docs/ballots/2026-09-19-disabled-input-parity.md` for the full ruling, including the D1 form-data-hazard rider (Input-Radio-Base) and the D2 optional dev-warn allowance captured below.
+
 **Contract Definition**: Component has no disabled state. Interaction affordances are always active; unavailable actions are handled by not rendering the component (or by another contract — see Philosophy Alternatives below), never by disabling it in place.
 
 **Rationale**: DesignerPunk does not support disabled states for usability and accessibility reasons. If an action is unavailable, the component should not be rendered.
@@ -335,6 +337,9 @@ disabled_state_exclusion_guard_checklist:
     - [ ] Web: no disabled/aria-disabled attribute, no tabindex=-1 for disabled reasons
     - [ ] iOS: no `.disabled()` modifier applied
     - [ ] Android: no `enabled = false` in semantics
+
+  optional_dev_warn_validation:
+    - [ ] (D2, optional — not a guard failure either way) A component MAY emit a development-gated warning (e.g. `NODE_ENV === 'development'`) naming the no-disabled-states philosophy and its three alternatives (state_loading, validate-on-press, do-not-render — see Philosophy Alternatives below) when a consumer sets `disabled`. This is adopted at scaffolding time for a new component, not retrofitted onto existing ones. Precedent for the dev-gated pattern (not the disabled topic itself): `Progress-Stepper-Base/platforms/web/ProgressStepperBase.web.ts:202-216`.
 ```
 
 **Philosophy Alternatives** — when a spec's design outline reaches for "disabled," redirect to the pattern that actually fits:

package/governance/Test-Development-Standards.md

@@ -1983,10 +1983,10 @@ console.log(reporter.generateReport());
 ### Quick Reference: Validation Commands
 
 ```bash
-# Linting validation
-npm run lint:stemma                    # Run all Stemma validators
-npm run lint:stemma:naming             # Component naming only
-npm run lint:stemma:tokens             # Token usage only
+# Stemma validation (no standalone lint:stemma* scripts exist — naming and
+# token-usage validators (StemmaComponentNamingValidator, StemmaTokenUsageValidator)
+# are exercised via *.stemma.test.ts files, run through the normal test command below)
+npm test -- --testPathPattern=stemma   # Stemma contract tests only
 
 # Unit tests
 npm test -- path/to/component.test.ts  # Single test file

package/governance/Token-Family-Accessibility.md

@@ -170,7 +170,7 @@ object DesignTokens {
 
 ## Tap Area Tokens
 
-Tap area tokens ensure touch targets meet accessibility requirements for users with motor impairments. The system uses precision-targeted multipliers from a 44-unit base (WCAG 2.1 AA minimum).
+Tap area tokens ensure touch targets meet accessibility requirements for users with motor impairments. The system uses precision-targeted multipliers from a 44-unit base — the WCAG 2.5.5 Target Size (Level AAA) threshold, which also exceeds the 24×24 WCAG 2.2 AA minimum (SC 2.5.8).
 
 ### WCAG Requirements
 
@@ -186,7 +186,7 @@ Tap area tokens ensure touch targets meet accessibility requirements for users w
 
 | Token Name | Value | Multiplier | Grid Alignment | Use Case |
 |------------|-------|------------|----------------|----------|
-| `tapAreaMinimum` | 44px/pt/dp | 1.00× | No | WCAG 2.1 AA minimum |
+| `tapAreaMinimum` | 44px/pt/dp | 1.00× | No | WCAG 2.5.5 AAA target size |
 | `tapAreaRecommended` | 48px/pt/dp | 1.09× | Yes (8×6) | Enhanced usability |
 | `tapAreaComfortable` | 56px/pt/dp | 1.27× | Yes (8×7) | Spacious interaction |
 | `tapAreaGenerous` | 64px/pt/dp | 1.45× | Yes (8×8) | Extra spacious |
@@ -197,7 +197,7 @@ Tap area tokens ensure touch targets meet accessibility requirements for users w
 
 **Mathematical Relationship**: base × 1 = 44 × 1 = 44
 
-**WCAG Compliance**: 2.5.5 Target Size (Level AAA)
+**WCAG Compliance**: 2.5.5 Target Size (Level AAA). Also exceeds SC 2.5.8 Target Size (Minimum), the WCAG 2.2 Level AA threshold of 24×24.
 
 **Use Cases**:
 - Minimum acceptable touch target size
@@ -209,7 +209,7 @@ Tap area tokens ensure touch targets meet accessibility requirements for users w
 - iOS: 44pt
 - Android: 44dp
 
-**Note**: While this meets WCAG AAA, consider using `tapAreaRecommended` for better usability.
+**Note**: This is the system's floor, not a ceiling — it already satisfies the AAA target-size criterion, but consider `tapAreaRecommended` (48) for better usability and Material Design alignment.
 
 #### tapAreaRecommended (48 units)
 
@@ -339,11 +339,13 @@ validateTapAreaAccessibility(tapAreaValue: number): {
 }
 
 // Examples:
-validateTapAreaAccessibility(44)  // { isAccessible: true, level: 'AA' }
-validateTapAreaAccessibility(48)  // { isAccessible: true, level: 'AAA' }
-validateTapAreaAccessibility(32)  // { isAccessible: false, level: 'Below AA', recommendation: '...' }
+validateTapAreaAccessibility(44)  // { isAccessible: true, level: 'AAA' }  — SC 2.5.5
+validateTapAreaAccessibility(32)  // { isAccessible: true, level: 'AA' }   — SC 2.5.8 (≥24)
+validateTapAreaAccessibility(20)  // { isAccessible: false, level: 'Below AA', recommendation: '...' }
 ```
 
+**Thresholds**: `≥44` → AAA (SC 2.5.5 Target Size); `≥24` → AA (SC 2.5.8 Target Size (Minimum), WCAG 2.2); `<24` → below the AA minimum. The function checks size only — SC 2.5.8's spacing and equivalent-alternative exceptions must be evaluated in component context.
+
 ---
 
 ## Icon Tokens
@@ -511,16 +513,18 @@ Icon(
 
 ---
 
-## WCAG 2.1 AA Compliance Summary
+## WCAG Compliance Summary
+
+The system's baseline posture is WCAG 2.1 AA. Tap area tokens go beyond that baseline: the 44-unit floor satisfies the Level AAA target-size criterion.
 
 ### Success Criteria Coverage
 
-| WCAG Criterion | Level | Token Category | Implementation |
-|----------------|-------|----------------|----------------|
-| 2.4.7 Focus Visible | AA | Focus Indicators | `accessibility.focus.*` tokens |
-| 1.4.11 Non-text Contrast | AA | Focus Indicators | `accessibility.focus.color` (3:1 minimum) |
-| 2.5.5 Target Size | AAA | Tap Areas | `tapAreaMinimum` (44px) |
-| 2.5.8 Target Size (Minimum) | AA | Tap Areas | All tap area tokens exceed 24px minimum |
+| WCAG Criterion | Version | Level | Token Category | Implementation |
+|----------------|---------|-------|----------------|----------------|
+| 2.4.7 Focus Visible | 2.1 | AA | Focus Indicators | `accessibility.focus.*` tokens |
+| 1.4.11 Non-text Contrast | 2.1 | AA | Focus Indicators | `accessibility.focus.color` (3:1 minimum) |
+| 2.5.5 Target Size | 2.1 | AAA | Tap Areas | `tapAreaMinimum` (44px) |
+| 2.5.8 Target Size (Minimum) | 2.2 | AA | Tap Areas | All tap area tokens exceed the 24px minimum |
 
 ### Compliance Checklist
 

package/governance/Token-Family-Blend.md

@@ -67,7 +67,8 @@ Semantic blend tokens provide contextual meaning for common color modification u
 |------------|-----------|-----------|-------|----------|
 | `blend.hoverDarker` | blend200 | darker | 8% | Standard hover feedback on light backgrounds |
 | `blend.hoverLighter` | blend200 | lighter | 8% | Hover feedback on dark backgrounds |
-| `blend.pressedDarker` | blend300 | darker | 12% | Pressed state feedback |
+| `blend.pressedDarker` | blend300 | darker | 12% | Pressed state feedback on light backgrounds |
+| `blend.pressedLighter` | blend300 | lighter | 12% | Pressed state feedback on dark backgrounds |
 | `blend.focusSaturate` | blend200 | saturate | 8% | Focus state with increased saturation |
 | `blend.disabledDesaturate` | blend300 | desaturate | 12% | **DEPRECATED 2026-07-15** — no disabled states in DesignerPunk; removal at next major |
 | `blend.containerHoverDarker` | blend100 | darker | 4% | Subtle container/surface hover |
@@ -495,10 +496,10 @@ blend500 = base × 5 = 0.04 × 5 = 0.20 (20%)
 - **Semantic Blend Source**: `src/tokens/semantic/BlendTokens.ts` - Semantic blend token definitions
 - **Theme-Aware Utilities**: `src/blend/ThemeAwareBlendUtilities.web.ts` - Web platform utilities
 - **Token System Overview**: `docs/token-system-overview.md` - Complete token system reference
-- **Color Tokens Guide**: `.kiro/steering/Token-Family-Color.md` - Color token reference
+- **Color Tokens Guide**: `token-family-color` - Color token reference
 - **Blend Infrastructure Spec**: `.kiro/specs/031-blend-infrastructure-implementation/design.md` - Architecture and design decisions
-- **Component Development Guide**: `.kiro/steering/Component-Development-Guide.md` - Token usage in component development
-- **Token Resolution Patterns**: `.kiro/steering/Token-Resolution-Patterns.md` - Strategic guidance on token type selection and validation
+- **Component Development Guide**: `component-development-guide` - Token usage in component development
+- **Token Resolution Patterns**: `token-resolution-patterns` - Strategic guidance on token type selection and validation
 
 ---
 

package/governance/Token-Family-Blur.md

@@ -49,16 +49,16 @@ Different blur contexts consume different ranges of the scale. The blur primitiv
 
 ### Shadow Context
 
-Shadow composites (`shadow.sm`, `shadow.md`, etc.) reference blur primitives as one property among several (offset, opacity, color). The blur value controls edge softness.
+Shadow composites (`shadow.container`, `shadow.modal`, etc.) reference blur primitives as one property among several (offset, opacity, color). The blur value controls edge softness.
 
-| Shadow Use | Blur Token | Value | Effect |
+| Shadow Use | Blur Token | Value | Consuming shadow tokens |
 |-----------|------------|-------|--------|
-| No shadow | `blur000` | 0 | No blur |
-| Sharp edges | `blur025` | 4 | Hard, defined edges |
-| Standard UI | `blur075` | 12 | Balanced definition |
-| Raised elements | `blur100` | 16 | Increased blur for depth |
-| Subtle/hover | `blur125` | 20 | Diffuse, gentle edges |
-| Floating elements | `blur150` | 24 | Maximum shadow blur |
+| No shadow | `blur000` | 0 | `shadow.none` |
+| Sharp edges | `blur025` | 4 | `shadow.fab`, `shadow.navigation.indicator` |
+| Standard UI | `blur075` | 12 | `shadow.container`, `shadow.dropdown`, `shadow.sunrise`–`shadow.sunset` |
+| Raised elements | `blur100` | 16 | `shadow.modal` |
+| Subtle/hover | `blur125` | 20 | `shadow.navigation`, `shadow.hover` |
+| Floating elements | `blur150` | 24 | `shadow.toast`, `shadow.tooltip` |
 
 See also: [Token-Family-Shadow.md](token-family-shadow) for complete shadow composite documentation.
 

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.