mythik 0.0.1 → 0.1.0

package/docs/wiki/compiled/concept-form-state-paths.md

@@ -0,0 +1,55 @@
+---
+id: concept-form-state-paths
+title: Form state paths — `/ui/forms/{id}/*`
+kind: concept
+sources: [docs/consumer/ai-context.md#forms, docs/consumer/reference-doc.md#form-state-auto-generated]
+---
+
+# Form state paths
+
+When a form is declared in `spec.forms`, the framework reserves the
+`/ui/forms/{formId}/*` subtree for that form's state. **Internal keys
+(`__valid`, `__touched`, `__errors`)** are framework-owned.
+
+## Auto-generated paths
+
+| Path | Type | Description |
+|---|---|---|
+| `/ui/forms/{id}/isValid` | boolean | All fields valid (even untouched) |
+| `/ui/forms/{id}/errorCount` | number | Total displayed errors |
+| `/ui/forms/{id}/isDirty` | boolean | Any value changed |
+| `/ui/forms/{id}/fields/{field}/errors` | string[] | Error messages (shown only when touched) |
+| `/ui/forms/{id}/fields/{field}/touched` | boolean | User has interacted |
+| `/ui/forms/{id}/fields/{field}/dirty` | boolean | Value differs from initial |
+
+## Behavior
+
+- **`isValid` reflects actual validity** even for untouched fields
+  (so you can disable submit before user touches anything).
+- **`errors` show only for touched fields** — no error messages on
+  fields the user hasn't interacted with yet.
+
+## Read patterns
+
+Submit gate:
+```json
+"disabled": { "$not": { "$state": "/ui/forms/task-form/isValid" } }
+```
+
+First error message:
+```json
+{ "$array": "first", "source": { "$state": "/ui/forms/task-form/fields/title/errors" } }
+```
+
+## Related concepts
+
+- [[@concept-forms]]
+- [[@concept-state-protection]]
+- [[@action-form-control]]
+- [[@action-submit-form]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Forms → Auto-generated state`
+- `docs/consumer/reference-doc.md § Form State (auto-generated)`
+- `docs/consumer/ai-context-runtime-semantics.md § 2.6`

package/docs/wiki/compiled/concept-forms.md

@@ -0,0 +1,89 @@
+---
+id: concept-forms
+title: `forms` — declarative form validation
+kind: concept
+sources: [docs/consumer/ai-context.md#forms, docs/consumer/reference-doc.md#form-validation-forms]
+---
+
+# `forms` — declarative form validation
+
+Top-level `forms` block coordinates multiple fields as a unit. Tracks
+form-level validity, supports cross-field rules, and gates `submitForm`.
+**Opt-in** — existing inline `checks` on inputs continue to work.
+
+## Shape / Signature
+
+```json
+"forms": {
+  "task-form": {
+    "fields": {
+      "title": {
+        "statePath": "/form/title",
+        "rules": [{ "type": "required", "message": "Title is required" }]
+      },
+      "email": {
+        "statePath": "/form/email",
+        "rules": [{ "type": "required" }, { "type": "email" }]
+      },
+      "maxPrice": {
+        "statePath": "/form/maxPrice",
+        "rules": [
+          { "type": "greaterThan", "args": { "other": { "$state": "/form/minPrice" } }, "message": "Max must exceed min" }
+        ]
+      }
+    },
+    "validateOn": "blur"
+  }
+}
+```
+
+## Auto-generated state
+
+| Path | Type | Description |
+|---|---|---|
+| `/ui/forms/{id}/isValid` | boolean | All fields valid (even untouched — for submit-button state) |
+| `/ui/forms/{id}/errorCount` | number | Total displayed errors |
+| `/ui/forms/{id}/isDirty` | boolean | Any value changed |
+| `/ui/forms/{id}/fields/{field}/errors` | string[] | Error messages (shown only when touched) |
+| `/ui/forms/{id}/fields/{field}/touched` | boolean | User has interacted |
+| `/ui/forms/{id}/fields/{field}/dirty` | boolean | Value differs from initial |
+
+## Examples
+
+Disable submit until valid:
+```json
+"disabled": { "$not": { "$state": "/ui/forms/task-form/isValid" } }
+```
+
+Show inline error:
+```json
+"error-text": {
+  "type": "text",
+  "visible": { "$array": "count", "source": { "$state": "/ui/forms/task-form/fields/title/errors" } },
+  "props": {
+    "content": { "$array": "first", "source": { "$state": "/ui/forms/task-form/fields/title/errors" } },
+    "style": { "color": "#EF4444" }
+  }
+}
+```
+
+Submit with validation gate:
+```json
+{ "action": "submitForm", "params": { "formId": "task-form", "url": "...", "method": "POST", "body": {...} } }
+```
+
+## Form actions
+
+- [[@action-submit-form]] — preferred submission action
+- [[@action-form-control]] — `validateForm` / `touchField` / `resetForm`
+
+## Related concepts
+
+- [[@concept-form-state-paths]]
+- [[@concept-validators-catalog]]
+- [[@pattern-form-validation-cross-field]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Forms`
+- `docs/consumer/reference-doc.md § Form Validation (forms)`

package/docs/wiki/compiled/concept-identity-accent-application.md

@@ -0,0 +1,48 @@
+---
+id: concept-identity-accent-application
+title: `identity.accentApplication` — where accent appears
+kind: concept
+sources: [docs/consumer/ai-context.md#identity-system-forge, docs/consumer/reference-doc.md#rule-134]
+---
+
+# `identity.accentApplication`
+
+Controls where the accent color appears.
+
+## Fields
+
+| Field | Type | Effect |
+|---|---|---|
+| `buttons` | boolean | buttonPrimary uses accent |
+| `navItems` | boolean | Highlights active nav |
+| `cardLine` | array | Accent border on cards. Multi-select positions: `["top", "left"]` for L-shape |
+| `links` | boolean | Link color |
+| `backgrounds` | boolean | Section bg uses accentLight |
+| `iconContainers` | boolean | Icon container bg |
+
+## Example
+
+L-shape accent border on cards:
+```json
+"tokens": {
+  "identity": {
+    "accentApplication": { "cardLine": ["top", "left"], "buttons": false }
+  }
+}
+```
+
+## Mechanism
+
+Applied inside `resolveSurfaceStyles` via `SurfaceOptions.accent` /
+`cardLine` / `accentButtons`.
+
+## Related concepts
+
+- [[@concept-identity-overview]]
+- [[@concept-identity-color-weight]] — different axis (where COLOR appears)
+- [[@concept-identity-helpers]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Identity System (Forge) → Accent Application`
+- `docs/consumer/reference-doc.md § rule 134`

package/docs/wiki/compiled/concept-identity-animations.md

@@ -0,0 +1,48 @@
+---
+id: concept-identity-animations
+title: `identity.animations` — cascade level 1
+kind: concept
+sources: [docs/consumer/ai-context.md#interactive-states--animations, docs/consumer/reference-doc.md#rule-223]
+---
+
+# `identity.animations`
+
+App-wide animation defaults. **Level 1** of the 5-level animation cascade —
+applies to every element, **including primitives inside custom-element
+expansions**.
+
+## Shape / Signature
+
+```json
+"tokens": {
+  "identity": {
+    "animations": { "mount": { "recipe": "fade-up" } }
+  }
+}
+```
+
+## Cascade behavior
+
+- Reaches inside custom-element expansions — the consumer cannot block
+  identity-level animations (black-box boundary preserves identity
+  cascade).
+- Per-trigger `null` at lower cascade levels disables the inherited
+  animation. See [[@concept-animation-null-semantics]].
+
+## Why this is useful
+
+Avoid repeating `animations: { mount: { recipe: 'fade-up' } }` on every
+element. Declare it once in `identity.animations` and let the cascade
+propagate.
+
+## Related concepts
+
+- [[@concept-animation-cascade]]
+- [[@concept-animation-null-semantics]]
+- [[@concept-animations-engine]]
+- [[@concept-identity-overview]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Interactive States & Animations → Cascade level 1`
+- `docs/consumer/reference-doc.md § rule 223`

package/docs/wiki/compiled/concept-identity-border-elevation-override.md

@@ -0,0 +1,56 @@
+---
+id: concept-identity-border-elevation-override
+title: Identity border + elevation overrides
+kind: concept
+sources: [docs/consumer/ai-context.md#identity-system-forge, docs/consumer/reference-doc.md#rules-161-162]
+---
+
+# Identity border + elevation overrides
+
+`identity.borderWidth`, `borderStyle`, `borderColor`, `elevationStyle`,
+`elevationColor` override surface-produced borders/shadows. **Both default
+`false` — surface type controls everything until explicitly enabled.**
+
+## Override flags (both default `false`)
+
+| Flag | Scope |
+|---|---|
+| `overrideSurfaceBorders: true` | Card + modal |
+| `overrideInputButtons: true` | Input + buttonPrimary + buttonSecondary |
+
+## Override fields
+
+| Field | Type / values |
+|---|---|
+| `borderWidth` | number (px) |
+| `borderStyle` | CSS border-style |
+| `borderColor` | semantic — `'neutral'` / `'primary'` / `'accent'` / `'text'` |
+| `elevationStyle` | `'none'` / `'diffuse'` / `'solid'` / `'color'` |
+| `elevationColor` | semantic — `'dark'` (`#000000`) / `'primary'` / `'accent'` |
+
+## Elevation styles
+
+| Value | Effect |
+|---|---|
+| `none` | No shadow |
+| `diffuse` | Soft blur shadow, rgba |
+| `solid` | No-blur offset shadow, direct color (comic-book style) |
+| `color` | Blur shadow using `elevationColor` in rgba |
+
+Shadow angle decomposed via sin/cos matching the surface serializer's
+`shadowToCSS` pattern. `depthScale()` modulates intensity.
+
+## inputFocus is never overridden
+
+Accessibility — `inputFocus` styles preserve the framework's behavior
+even when border/elevation overrides are enabled.
+
+## Related concepts
+
+- [[@concept-identity-surface]]
+- [[@concept-identity-overview]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § rule 58`
+- `docs/consumer/reference-doc.md § rules 161-162`

package/docs/wiki/compiled/concept-identity-color-scheme.md

@@ -0,0 +1,74 @@
+---
+id: concept-identity-color-scheme
+title: `identity.colorScheme` - surface polarity
+kind: concept
+sources: [docs/consumer/ai-context.md#identity-system-forge, docs/consumer/reference-doc.md#rule-130]
+---
+
+# `identity.colorScheme`
+
+3 surface-polarity modes. Affects surfaces only; `t.colors` stays the
+original palette so UI controls remain readable.
+
+## Catalog
+
+| Value | Effect |
+|---|---|
+| `light-surface` | (default) Pass-through |
+| `dark-surface` | Uses `modes.dark` from DNA |
+| `colored-surface` | 3 configurable tonal layers from primary palette |
+
+`"light"` and `"dark"` are not valid values. Lint validates
+`tokens.identity.colorScheme` in both AppSpec and screen Spec tokens before
+render.
+
+## Colored Surface Layers
+
+```json
+"tokens": {
+  "identity": {
+    "colorScheme": "colored-surface",
+    "coloredSurfaceLayers": { "background": 25, "surface": 45, "primitive": 65 }
+  }
+}
+```
+
+The 3 numbers are OKLCH lightness steps (0-100). Each produces a distinct
+layer:
+
+- Page background (darkest)
+- Cards (mid)
+- Inputs (lightest)
+
+Default 25/45/65 validated across 8 hues. Focus ring uses **accent** (not
+primary) in colored-surface to avoid invisible ring on primary background.
+
+## `t.colors` stays original
+
+`t.colors.text` returns the original light palette text color. Surface
+styles use scheme-adjusted colors internally. This separation ensures UI
+controls (selects, labels) remain readable while preview/app content
+adapts to the scheme.
+
+## Preview text uses `schemeColors`
+
+For preview elements that should reflect the scheme, use
+`{ "$token": "schemeColors.text" }`.
+
+## Glass + dark scheme
+
+`hexToRgba(c.surface, opacity)` derives rgba from the actual surface color.
+Dark scheme + glass = semi-transparent dark, not semi-transparent white
+(rule 132).
+
+## Related concepts
+
+- [[@concept-identity-overview]]
+- [[@concept-identity-color-weight]]
+- [[@concept-token-categories]] - `schemeColors.*`
+- [[@concept-auto-dark-mode]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md` - Identity System (Forge) / Color Scheme
+- `docs/consumer/reference-doc.md` - rules 130-132

package/docs/wiki/compiled/concept-identity-color-weight.md

@@ -0,0 +1,50 @@
+---
+id: concept-identity-color-weight
+title: `identity.colorWeight` — where color appears
+kind: concept
+sources: [docs/consumer/ai-context.md#identity-system-forge, docs/consumer/reference-doc.md#rule-133]
+---
+
+# `identity.colorWeight`
+
+5 modes controlling where color appears in the layout. Resolved values
+exposed as `$token: colorWeight.*` in specs.
+
+## Catalog
+
+| Value | Effect |
+|---|---|
+| `monochrome` | All neutral |
+| `branded-nav` | Primary navbar, white text |
+| `gradient-hero` | Primary→accent gradient hero section |
+| `ambient` | Subtle primary tint on sections via rgba |
+| `dark-native` | Dark nav using `modes.dark` |
+
+## Resolved values (`resolveColorWeight()`)
+
+`{ navBg, navText, sectionBg, heroBg, heroGradient }` — always returns
+defined values. Non-gradient modes return `'transparent'` / `'none'`
+instead of undefined (rule 138) — prevents `$token` resolution errors.
+
+## Use in specs
+
+```json
+"sidebar": {
+  "type": "box",
+  "style": {
+    "backgroundColor": { "$token": "colorWeight.navBg" },
+    "color": { "$token": "colorWeight.navText" }
+  }
+}
+```
+
+## Related concepts
+
+- [[@concept-identity-overview]]
+- [[@concept-identity-accent-application]] — different axis (where ACCENT appears)
+- [[@concept-token-categories]] — `colorWeight.*` paths
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Identity System (Forge) → Color Weight`
+- `docs/consumer/reference-doc.md § rule 133, 138`

package/docs/wiki/compiled/concept-identity-glass-rn.md

@@ -0,0 +1,46 @@
+---
+id: concept-identity-glass-rn
+title: Glass surface on React Native — BlurView
+kind: concept
+sources: [docs/consumer/ai-context-primitives.md#accordion, docs/consumer/reference-doc.md#rule-141]
+---
+
+# Glass surface on React Native — BlurView
+
+When `identity.surface === 'glass'`, RN primitives wrap content in
+`<BlurView>` from `expo-blur`. **No spec changes needed** — the surface
+treatment handles it automatically.
+
+## Affected RN primitives
+
+`accordion`, `input`, `modal`, `select`, `textarea` — all wrap content in
+`<BlurView>` when `surface === 'glass'`.
+
+## Mechanism
+
+The RN serializer (`surfaceToRN`) passes `blur: { radius }` through to
+surface props. RN primitives detect blur and wrap. `toViewStyle()` strips
+`blur` and `focusRing` from surface props before spreading into RN style
+objects.
+
+## Glass border uses semi-transparent rgba
+
+Glass surface borders use `hexToRgba(c.surface, 0.2)` for cards/modal/secondary
+and `hexToRgba(c.surface, 0.15)` for inputs (rule 142). Glass `inputFocus`
+border uses `c.primary + '80'` (50% opacity hex suffix).
+
+## BlurView in tests
+
+`react-native-svg` mock drops the `animatedProps` prop before spreading to
+DOM so React doesn't emit "Unknown DOM prop" warnings on every test render.
+
+## Related concepts
+
+- [[@concept-identity-surface]]
+- [[@concept-identity-helpers]]
+- [[@expression-platform]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § accordion (RN glass support note)`
+- `docs/consumer/reference-doc.md § rule 141, 142`

package/docs/wiki/compiled/concept-identity-gradients.md

@@ -0,0 +1,56 @@
+---
+id: concept-identity-gradients
+title: `identity.gradients` — gradient text + buttons
+kind: concept
+sources: [docs/consumer/ai-context.md#identity-system-forge, docs/consumer/reference-doc.md#rules-145-146-150-151]
+---
+
+# `identity.gradients`
+
+Apply primary→accent gradient to headings or primary buttons.
+
+## Fields
+
+| Field | Accepts | Effect |
+|---|---|---|
+| `text` | `boolean` \| `'vibrant'` \| `'soft'` \| `'muted'` | Apply `background-clip: text` on headings. Spec `style.color` overrides |
+| `buttons` | `boolean` \| `'vibrant'` \| `'soft'` \| `'muted'` | Apply `linear-gradient(135deg, primary, accent)` on primary buttons. Spec `style.background` overrides |
+
+`true` maps to `vibrant`. Both web-only (RN deferred — requires
+`expo-linear-gradient`).
+
+## Modes
+
+| Mode | Effect |
+|---|---|
+| `vibrant` | OKLCH primary→accent (rich, saturated) |
+| `soft` | OKLCH primaryLight→accentLight (subtle) |
+| `muted` | sRGB primary→accent (desaturated middle, luxury/editorial) |
+
+## OKLCH interpolation
+
+All gradient text + buttons use `linear-gradient(in oklch, ...)` for
+vibrant transitions. sRGB interpolation crosses through desaturated
+midpoints (purple→gold = muddy brown); OKLCH maintains saturation through
+the hue arc. Graceful degradation on older browsers.
+
+## Example
+
+```json
+"tokens": { "identity": {
+  "gradients": { "text": "vibrant", "buttons": "soft" }
+}}
+```
+
+## Related concepts
+
+- [[@concept-identity-overview]]
+- [[@concept-identity-typography-hierarchy]]
+- [[@concept-identity-heading-color]] — gradient takes precedence
+- [[@primitive-text]]
+- [[@primitive-button]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Identity System (Forge)`
+- `docs/consumer/reference-doc.md § rules 145-146, 150-151`

package/docs/wiki/compiled/concept-identity-heading-color.md

@@ -0,0 +1,40 @@
+---
+id: concept-identity-heading-color
+title: `identity.headingColor`
+kind: concept
+sources: [docs/consumer/ai-context.md#identity-system-forge, docs/consumer/reference-doc.md#rule-165]
+---
+
+# `identity.headingColor`
+
+Controls heading text color via 4 modes.
+
+## Catalog
+
+`'default'` (inherit from container — default), `'primary'`, `'accent'`,
+`'primary-dark'`. Resolves to scheme colors.
+
+## Priority
+
+`style.color > gradient (gradients.text) > headingColor > inherit`
+
+When `gradients.text` is active, gradient takes precedence. When
+`style.color` is set on the element, that takes precedence over both.
+
+## Example
+
+```json
+"tokens": { "identity": { "headingColor": "primary" } }
+```
+
+## Related concepts
+
+- [[@concept-identity-typography-hierarchy]]
+- [[@concept-identity-gradients]]
+- [[@concept-identity-color-scheme]]
+- [[@primitive-text]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Identity System (Forge)`
+- `docs/consumer/reference-doc.md § rule 165`

package/docs/wiki/compiled/concept-identity-helpers.md

@@ -0,0 +1,61 @@
+---
+id: concept-identity-helpers
+title: Identity helpers — resolve API
+kind: concept
+sources: [docs/consumer/ai-context.md#identity-system-forge, docs/consumer/reference-doc.md#rules-114-129]
+---
+
+# Identity helpers — resolve API
+
+Functions that compose the identity system into platform-neutral
+structured data. Useful for custom renderers / consumers.
+
+## `resolveIdentity<T>(input, serializer)` — unified orchestrator
+
+Single function that orchestrates: `resolveSchemeColors → generateTonalStep
+→ resolveSurfaceStyles → serializer(T) → resolveColorWeight →
+resolveRadiusPattern`. Accepts a `SurfaceSerializer<T>` — each platform
+passes its own (`surfaceToCSS`, `surfaceToRN`).
+
+Returns `{ schemeColors, surface: T, colorWeight, radius }`.
+
+## `resolveSurfaceStyles()`
+
+Returns `StructuredSurfaceStyles` with 6 component categories: `card`,
+`input`, `inputFocus`, `buttonPrimary`, `buttonSecondary`, `modal`. Each
+is a `StructuredSurfaceStyleProps` with `backgroundColor?`, `color?`,
+`border?: BorderDef`, `borderTop/Right/Bottom/Left?: BorderDef`, `shadows:
+ShadowDef[]`, `blur?: BlurDef`, `backgroundOpacity?`. **NO CSS strings —
+data only.**
+
+## Platform serializers
+
+- **`surfaceToCSS()`** — for web (React/Vue/Angular/Svelte).
+- **`surfaceToRN()`** — for React Native. `toViewStyle()` helper strips
+  `blur` and `focusRing` from surface props before spreading into RN
+  style objects.
+
+## Depth + angle are serializer concerns
+
+`identity.depth` (0-1) and `identity.shadowAngle` (0-360°) are NOT in
+`StructuredSurfaceStyleProps`. Shadows store raw `magnitude`/`blur`/`opacity`.
+The serializer applies `depthScale()` and sin/cos angle rotation when
+converting to platform-specific format.
+
+## Module structure
+
+`packages/core/src/design/identity/` with 8 focused modules:
+`types.ts`, `surface.ts`, `shape.ts`, `elevation.ts`, `typography.ts`,
+`color.ts`, `background.ts`, `motion.ts`. Barrel `index.ts` re-exports all
+public API.
+
+## Related concepts
+
+- [[@concept-identity-overview]]
+- [[@concept-identity-surface]]
+- [[@concept-where-to-look]] — for custom serializer development
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Identity System (Forge) → Architecture`
+- `docs/consumer/reference-doc.md § rules 114, 128, 129, 160`

package/docs/wiki/compiled/concept-identity-icons.md

@@ -0,0 +1,46 @@
+---
+id: concept-identity-icons
+title: `identity.icons` — icon defaults
+kind: concept
+sources: [docs/consumer/ai-context.md#identity-system-forge, docs/consumer/reference-doc.md#rule-143]
+---
+
+# `identity.icons`
+
+Default `weight` for all icons + auto-wrap container.
+
+## Fields
+
+| Field | Type | Effect |
+|---|---|---|
+| `weight` | string | Default for all icon primitives. Spec `weight` overrides |
+| `container` | string | `'none'` / `'circle'` / `'square'` / `'rounded-square'` — auto-wraps with colored bg. `container={false}` in spec suppresses |
+| `containerColor` | string | `'primary'` / `'accent'` / `'muted'` / `'surface'` |
+
+## Example
+
+```json
+"tokens": { "identity": {
+  "icons": { "weight": "bold", "container": "circle", "containerColor": "primary" }
+}}
+```
+
+Spec icon (overrides default `weight`):
+```json
+{ "type": "icon", "props": { "name": "pencil-simple", "weight": "regular" } }
+```
+
+Spec icon (suppresses container):
+```json
+{ "type": "icon", "props": { "name": "trash", "container": false } }
+```
+
+## Related concepts
+
+- [[@primitive-icon]]
+- [[@concept-identity-overview]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Identity System (Forge) → Identity icons`
+- `docs/consumer/reference-doc.md § rule 143`