docs(frontend): add architecture READMEs for ui, renderer, and desktop by Astro-Han · Pull Request #725 · apache/maka

Astro-Han · 2026-07-11T16:21:49Z

Summary

Add target-oriented architecture READMEs for the three frontend surfaces — packages/ui, the renderer, and the desktop app shell — to guide agents through the React + BaseUI + shadcn + Tailwind convergence.

Why

The convergence to React + BaseUI + shadcn + Tailwind is mostly in place, but the per-surface architecture lives nowhere locally. Agents entering packages/ui or the renderer have no map for the export layers, the app-shell split, the styles/tokens layout, or which transitional surfaces to retire. docs/ has the authoritative design-system contract (being refreshed by @jackwener) but nothing at the module level.

Direct docs request; no tracking issue.

Scope

Changed:

packages/ui/README.md — four export surfaces (primitives / ui.tsx / top-level features / components.tsx), the off-barrel convention, where new code goes, the ui.tsx→primitives convergence direction.
apps/desktop/src/renderer/README.md — the AppShell + app-shell-<scope>-<action> split, the styles/tokens layout (maka-tokens.css, reference-shell.css, styles/*.css), the primitive-first authoring rule, the transitional surfaces.
apps/desktop/README.md — the main/preload/renderer split, the main naming convention (*-ipc-main / *-main / *-guard), the IPC contract, the data flow.

Not included:

No code changes (pure docs).
No edits to docs/design-system.md or docs/frontend-css-governance.md (being refreshed by @jackwener; the READMEs only reference them).
No new docs/ files — the per-surface READMEs go in place, not in docs/.

Verification

Verified all 13 paths referenced in the READMEs exist.
Cross-checked facts against code: @maka/ui is consumed only by desktop; the main.tsx→app.tsx→AppShell chain; the renderer only import types from @maka/runtime / @maka/storage (runtime access goes through the preload maka bridge); app-shell.tsx is 1810 lines; maka-tokens.css is 73KB; Badge moved to primitives/ via refactor(ui): converge unmanaged design specs (line-height, font-weight, letter-spacing, …) #520 PR9; buttonVariants lives in ui.tsx; the preload exposes the maka namespace with <domain>:<action> IPC channels.
No build/test run — pure docs PR, no code change.

User-facing impact

None. Docs only.

Reviewer notes

Three commits, one per README, per the "smallest independently-revertible intent" commit unit — each README is self-contained; reverting one leaves the other two usable.
Transitional surfaces are described with direction + end state only — no TODOs, no progress, no time-sensitive content (that stays in issues/PRs). The READMEs are meant not to rot.
design-system.md / frontend-css-governance.md references note they're being refreshed by @jackwener; code + contract tests are the source of truth until then.

Checklist

Scope matches the PR title and excludes unrelated changes
Verification lists commands/results, or explains why they were not run
User-facing impact, docs, changelog, migrations, and breaking changes are noted, or marked none
Risk, rollback, or review focus is called out for non-trivial changes
UI changes include screenshots/video, or explain why not applicable (N/A: docs only)

Target-oriented README for the shared UI package: four export surfaces (primitives / ui.tsx / top-level features / components.tsx), the off-barrel convention, the data-slot hook rule with its exceptions, where new code goes, and the ui.tsx→primitives convergence direction. Transitional surfaces are marked with direction + end state, not TODOs.

Target-oriented READMEs for the Electron app shell and its renderer: the main/preload/renderer split, the main naming convention, the three-pattern IPC contract and the registerIpc() registration step, the actual main.ts startup order, the renderer AppShell + app-shell-<scope>-<action> split, the styles/tokens layout (with the --foreground-N wash-vs-text split), and the primitive-first authoring rule. Direction + end state only, no TODOs.

- ui: drop the broken @maka/ui/icons ProviderLogo example (it lives in the renderer); note icons re-exports Lucide symbols; use markerVariants as a real off-barrel example instead of the zero-consumer LiveIndicator; clarify 'runtime consumer' (preload imports types). - renderer: describe AppShell slices as app-shell-* one-concern modules (not a strict two-segment rule several existing slices violate); make the reference-shell.css breadcrumb point at the file's own header. - desktop: fix startup order (window created early, background startup concurrent, handlers before renderer entry that prefetches pre-mount); route main→renderer push through safeSendToRenderer (raw webContents.send throws on destroyed windows); add src/global.d.ts to the new-IPC steps.

- desktop: window is created hidden, revealed after first AppShell paint (notifyRendererReady gate), not 'preload skeleton shows within ms'; drop the false 'background mutations always push via channels, UI converges lazily' invariant (interrupted-session recovery doesn't emit). - ui: scope the off-barrel 'don't re-export' rule to single in-package consumers with no cross-package consumer (previewVariants is re-exported for exactly that cross-package reason), resolving the contradiction with the promotion rule.

@theme

- desktop/renderer: window reveal has a fallback timer, and main.tsx's onboarding prefetch can time out to a fail-soft loading state — stop claiming 'only after first paint' / 'never sees skeleton' / 'no loading flash' as absolute paths. - renderer: maka-tokens.css is the main token source, but a few @theme Tailwind-bridge values (e.g. --shadow-maka-panel) live in styles.css and are contract-pinned there — document the exception instead of claiming a single source. - ui: clarify 'model-provider brand logos' (renderer settings/provider-*); bot-provider logos are in @maka/ui's bot-brand-logo.

- renderer: document the contract-pinned index.html inline .maka-preload skeleton (hardcoded colors, no CSS vars — maka-tokens.css hasn't loaded yet) as the narrow exception to 'styles.css is the only CSS entry'. - ui: resolve the barrel-rule contradiction — new feature components re-export from components.tsx, but only reach index.ts when they have a second or cross-package consumer (primitives are always re-exported).

…components.tsx) index.ts does 'export * from ./components.js', so re-exporting a feature component from components.tsx already puts it on the package barrel — there is no separate 'add to index.ts later' stage. Rule now: relative import while single in-package consumer; re-export from components.tsx (barrel follows automatically) once a second or cross-package consumer appears.

@theme

The @theme Tailwind bridge is split: most aliases (color/typography/spacing/ radius) live in maka-tokens.css, a few values (e.g. --shadow-maka-panel) in styles.css — both contract-pinned, so check which file owns a value before moving it. /* local: ... */ is the rule for new component-local vars; existing ones don't all carry it yet.

@theme

…split) Both maka-tokens.css and styles.css carry an @theme inline block, and their color aliases overlap (--color-background/accent/muted appear in both); styles.css also carries the typography/line-height/font-weight/tracking/ spacing/radius/shadow bridges. Each value's home is contract-pinned (spacing/letter-spacing/foreground-tier contracts), so stop describing it as a clean split and point to the owning contract instead.

@theme

- ui: barrel promotion is cross-package consumer or explicit public-API need, not 'second in-package consumer' (attachment-file-card has two in-package consumers but stays off-barrel); remove the markerVariants example that implied otherwise. - renderer: maka-tokens.css tail is a large recipe section (base/utilities/ recipes/animations), not 'a few fallbacks'; the @theme bridge overlap is concrete (--color-muted maps to --foreground-5 in styles.css but --muted in maka-tokens.css); only some bridge values are contract-pinned (spacing/letter-spacing/foreground-tier), overlapping color aliases are not — don't claim 'each' is pinned.

- renderer: stop claiming overlapping color aliases have no contract pin — some do (--color-control in styles.css via design-system-governance-406; --color-muted-foreground in maka-tokens.css via foreground-tier); only some (e.g. --color-background/accent/muted) are unpinned. - desktop: narrow the safe-send claim — the contract test scans a fixed file list for direct mainWindow.webContents.send forms; new *-ipc-main.ts files aren't auto-covered, so route through the guard in every new file. - ui: sync the index.ts and chat.tsx LiveIndicator comments to the README barrel rule (cross-package consumer or explicit public-API need, not a second in-package consumer; attachment-file-card precedent), so the README is the single source of the promotion rule.

…irement) The synced comments still described chat call sites and the tool stream as consumers, but #712 retired streamVariants/LiveIndicator from the tool body — they have no production consumer now (chat-stream-cascade-contract pins it). State that in the comments, and drop the contradictory 'LiveIndicator exported only on cross-package consumer' line so the promotion rule is stated once (cross-package consumer or explicit public-API need) and points to README.

…owner The barrel promotion rule is volatile when duplicated into inline source comments (consumer lists drift as symbols retire — e.g. streamVariants/ LiveIndicator in #712). Reverting the index.ts/chat.tsx comment edits keeps this PR docs-only and makes packages/ui/README.md the single source of truth (the README now says so explicitly). Cleaning up the stale source comments / dead symbols is a separate change.

Round 14 review: 'revert + README says comments may lag' still left the stale 'second consumer' / streamVariants/LiveIndicator consumer lists in the source comments, so the conflict source survived. Real root correction: the inline comments no longer re-derive the promotion rule or track consumers (that list drifts as symbols retire, e.g. #712) — they keep their local implementation intent and point at packages/ui/README.md for the rule. README stays the single owner; dead-symbol cleanup stays a separate change.

Round 15 found the prior root correction only covered 2 of the consumer/ promotion comment blocks; markerVariants/TextShimmer/toolVariants/previewVariants still re-derived the rule or tracked consumers, and streamVariants/LiveIndicator still assumed a call site that #712 removed. Exhaustively replace every such block: keep local implementation intent + a short pointer to the README, drop all consumer counts and promotion derivations. Also drop the README's 'inline comments may lag' line (no longer needed once the comments don't re-derive).

16 rounds of review showed cleaning inline source comments is a bottomless local patch: chat.tsx has many historical consumer/call-site mentions (incl. #712-retired streamVariants dead-code notes), and each fix surfaced an adjacent one. Root correction per receiving-code-review: keep this PR docs-only (3 READMEs), revert the index.ts/chat.tsx comment edits to main, and make packages/ui/README.md the single owner of the barrel promotion rule. Source-comment cleanup and dead- symbol removal are separate changes.

Astro-Han · 2026-07-11T16:21:49Z

Summary

Add target-oriented architecture READMEs for the three frontend surfaces — packages/ui, the renderer, and the desktop app shell — to guide agents through the React + BaseUI + shadcn + Tailwind convergence.

Why

The convergence to React + BaseUI + shadcn + Tailwind is mostly in place, but the per-surface architecture lives nowhere locally. Agents entering packages/ui or the renderer have no map for the export layers, the app-shell split, the styles/tokens layout, or which transitional surfaces to retire. docs/ has the authoritative design-system contract (being refreshed by @jackwener) but nothing at the module level.

Direct docs request; no tracking issue.

Scope

Changed:

packages/ui/README.md — four export surfaces (primitives / ui.tsx / top-level features / components.tsx), the off-barrel convention, where new code goes, the ui.tsx→primitives convergence direction.
apps/desktop/src/renderer/README.md — the AppShell + app-shell-<scope>-<action> split, the styles/tokens layout (maka-tokens.css, reference-shell.css, styles/*.css), the primitive-first authoring rule, the transitional surfaces.
apps/desktop/README.md — the main/preload/renderer split, the main naming convention (*-ipc-main / *-main / *-guard), the IPC contract, the data flow.

Not included:

No code changes (pure docs).
No edits to docs/design-system.md or docs/frontend-css-governance.md (being refreshed by @jackwener; the READMEs only reference them).
No new docs/ files — the per-surface READMEs go in place, not in docs/.

Verification

Verified all 13 paths referenced in the READMEs exist.
Cross-checked facts against code: @maka/ui is consumed only by desktop; the main.tsx→app.tsx→AppShell chain; the renderer only import types from @maka/runtime / @maka/storage (runtime access goes through the preload maka bridge); app-shell.tsx is 1810 lines; maka-tokens.css is 73KB; Badge moved to primitives/ via refactor(ui): converge unmanaged design specs (line-height, font-weight, letter-spacing, …) #520 PR9; buttonVariants lives in ui.tsx; the preload exposes the maka namespace with <domain>:<action> IPC channels.
No build/test run — pure docs PR, no code change.

User-facing impact

None. Docs only.

Reviewer notes

Three commits, one per README, per the "smallest independently-revertible intent" commit unit — each README is self-contained; reverting one leaves the other two usable.
Transitional surfaces are described with direction + end state only — no TODOs, no progress, no time-sensitive content (that stays in issues/PRs). The READMEs are meant not to rot.
design-system.md / frontend-css-governance.md references note they're being refreshed by @jackwener; code + contract tests are the source of truth until then.

Checklist

Scope matches the PR title and excludes unrelated changes
Verification lists commands/results, or explains why they were not run
User-facing impact, docs, changelog, migrations, and breaking changes are noted, or marked none
Risk, rollback, or review focus is called out for non-trivial changes
UI changes include screenshots/video, or explain why not applicable (N/A: docs only)

Target-oriented README for the shared UI package: four export surfaces (primitives / ui.tsx / top-level features / components.tsx), the off-barrel convention, the data-slot hook rule with its exceptions, where new code goes, and the ui.tsx→primitives convergence direction. Transitional surfaces are marked with direction + end state, not TODOs.

Target-oriented READMEs for the Electron app shell and its renderer: the main/preload/renderer split, the main naming convention, the three-pattern IPC contract and the registerIpc() registration step, the actual main.ts startup order, the renderer AppShell + app-shell-<scope>-<action> split, the styles/tokens layout (with the --foreground-N wash-vs-text split), and the primitive-first authoring rule. Direction + end state only, no TODOs.

- ui: drop the broken @maka/ui/icons ProviderLogo example (it lives in the renderer); note icons re-exports Lucide symbols; use markerVariants as a real off-barrel example instead of the zero-consumer LiveIndicator; clarify 'runtime consumer' (preload imports types). - renderer: describe AppShell slices as app-shell-* one-concern modules (not a strict two-segment rule several existing slices violate); make the reference-shell.css breadcrumb point at the file's own header. - desktop: fix startup order (window created early, background startup concurrent, handlers before renderer entry that prefetches pre-mount); route main→renderer push through safeSendToRenderer (raw webContents.send throws on destroyed windows); add src/global.d.ts to the new-IPC steps.

- desktop: window is created hidden, revealed after first AppShell paint (notifyRendererReady gate), not 'preload skeleton shows within ms'; drop the false 'background mutations always push via channels, UI converges lazily' invariant (interrupted-session recovery doesn't emit). - ui: scope the off-barrel 'don't re-export' rule to single in-package consumers with no cross-package consumer (previewVariants is re-exported for exactly that cross-package reason), resolving the contradiction with the promotion rule.

@theme

- desktop/renderer: window reveal has a fallback timer, and main.tsx's onboarding prefetch can time out to a fail-soft loading state — stop claiming 'only after first paint' / 'never sees skeleton' / 'no loading flash' as absolute paths. - renderer: maka-tokens.css is the main token source, but a few @theme Tailwind-bridge values (e.g. --shadow-maka-panel) live in styles.css and are contract-pinned there — document the exception instead of claiming a single source. - ui: clarify 'model-provider brand logos' (renderer settings/provider-*); bot-provider logos are in @maka/ui's bot-brand-logo.

- renderer: document the contract-pinned index.html inline .maka-preload skeleton (hardcoded colors, no CSS vars — maka-tokens.css hasn't loaded yet) as the narrow exception to 'styles.css is the only CSS entry'. - ui: resolve the barrel-rule contradiction — new feature components re-export from components.tsx, but only reach index.ts when they have a second or cross-package consumer (primitives are always re-exported).

…components.tsx) index.ts does 'export * from ./components.js', so re-exporting a feature component from components.tsx already puts it on the package barrel — there is no separate 'add to index.ts later' stage. Rule now: relative import while single in-package consumer; re-export from components.tsx (barrel follows automatically) once a second or cross-package consumer appears.

@theme

The @theme Tailwind bridge is split: most aliases (color/typography/spacing/ radius) live in maka-tokens.css, a few values (e.g. --shadow-maka-panel) in styles.css — both contract-pinned, so check which file owns a value before moving it. /* local: ... */ is the rule for new component-local vars; existing ones don't all carry it yet.

@theme

…split) Both maka-tokens.css and styles.css carry an @theme inline block, and their color aliases overlap (--color-background/accent/muted appear in both); styles.css also carries the typography/line-height/font-weight/tracking/ spacing/radius/shadow bridges. Each value's home is contract-pinned (spacing/letter-spacing/foreground-tier contracts), so stop describing it as a clean split and point to the owning contract instead.

@theme

- ui: barrel promotion is cross-package consumer or explicit public-API need, not 'second in-package consumer' (attachment-file-card has two in-package consumers but stays off-barrel); remove the markerVariants example that implied otherwise. - renderer: maka-tokens.css tail is a large recipe section (base/utilities/ recipes/animations), not 'a few fallbacks'; the @theme bridge overlap is concrete (--color-muted maps to --foreground-5 in styles.css but --muted in maka-tokens.css); only some bridge values are contract-pinned (spacing/letter-spacing/foreground-tier), overlapping color aliases are not — don't claim 'each' is pinned.

- renderer: stop claiming overlapping color aliases have no contract pin — some do (--color-control in styles.css via design-system-governance-406; --color-muted-foreground in maka-tokens.css via foreground-tier); only some (e.g. --color-background/accent/muted) are unpinned. - desktop: narrow the safe-send claim — the contract test scans a fixed file list for direct mainWindow.webContents.send forms; new *-ipc-main.ts files aren't auto-covered, so route through the guard in every new file. - ui: sync the index.ts and chat.tsx LiveIndicator comments to the README barrel rule (cross-package consumer or explicit public-API need, not a second in-package consumer; attachment-file-card precedent), so the README is the single source of the promotion rule.

…irement) The synced comments still described chat call sites and the tool stream as consumers, but #712 retired streamVariants/LiveIndicator from the tool body — they have no production consumer now (chat-stream-cascade-contract pins it). State that in the comments, and drop the contradictory 'LiveIndicator exported only on cross-package consumer' line so the promotion rule is stated once (cross-package consumer or explicit public-API need) and points to README.

…owner The barrel promotion rule is volatile when duplicated into inline source comments (consumer lists drift as symbols retire — e.g. streamVariants/ LiveIndicator in #712). Reverting the index.ts/chat.tsx comment edits keeps this PR docs-only and makes packages/ui/README.md the single source of truth (the README now says so explicitly). Cleaning up the stale source comments / dead symbols is a separate change.

Round 14 review: 'revert + README says comments may lag' still left the stale 'second consumer' / streamVariants/LiveIndicator consumer lists in the source comments, so the conflict source survived. Real root correction: the inline comments no longer re-derive the promotion rule or track consumers (that list drifts as symbols retire, e.g. #712) — they keep their local implementation intent and point at packages/ui/README.md for the rule. README stays the single owner; dead-symbol cleanup stays a separate change.

Round 15 found the prior root correction only covered 2 of the consumer/ promotion comment blocks; markerVariants/TextShimmer/toolVariants/previewVariants still re-derived the rule or tracked consumers, and streamVariants/LiveIndicator still assumed a call site that #712 removed. Exhaustively replace every such block: keep local implementation intent + a short pointer to the README, drop all consumer counts and promotion derivations. Also drop the README's 'inline comments may lag' line (no longer needed once the comments don't re-derive).

16 rounds of review showed cleaning inline source comments is a bottomless local patch: chat.tsx has many historical consumer/call-site mentions (incl. #712-retired streamVariants dead-code notes), and each fix surfaced an adjacent one. Root correction per receiving-code-review: keep this PR docs-only (3 READMEs), revert the index.ts/chat.tsx comment edits to main, and make packages/ui/README.md the single owner of the barrel promotion rule. Source-comment cleanup and dead- symbol removal are separate changes.

Astro-Han · 2026-07-11T16:21:49Z

Summary

Add target-oriented architecture READMEs for the three frontend surfaces — packages/ui, the renderer, and the desktop app shell — to guide agents through the React + BaseUI + shadcn + Tailwind convergence.

Why

The convergence to React + BaseUI + shadcn + Tailwind is mostly in place, but the per-surface architecture lives nowhere locally. Agents entering packages/ui or the renderer have no map for the export layers, the app-shell split, the styles/tokens layout, or which transitional surfaces to retire. docs/ has the authoritative design-system contract (being refreshed by @jackwener) but nothing at the module level.

Direct docs request; no tracking issue.

Scope

Changed:

packages/ui/README.md — four export surfaces (primitives / ui.tsx / top-level features / components.tsx), the off-barrel convention, where new code goes, the ui.tsx→primitives convergence direction.
apps/desktop/src/renderer/README.md — the AppShell + app-shell-<scope>-<action> split, the styles/tokens layout (maka-tokens.css, reference-shell.css, styles/*.css), the primitive-first authoring rule, the transitional surfaces.
apps/desktop/README.md — the main/preload/renderer split, the main naming convention (*-ipc-main / *-main / *-guard), the IPC contract, the data flow.

Not included:

No code changes (pure docs).
No edits to docs/design-system.md or docs/frontend-css-governance.md (being refreshed by @jackwener; the READMEs only reference them).
No new docs/ files — the per-surface READMEs go in place, not in docs/.

Verification

Verified all 13 paths referenced in the READMEs exist.
Cross-checked facts against code: @maka/ui is consumed only by desktop; the main.tsx→app.tsx→AppShell chain; the renderer only import types from @maka/runtime / @maka/storage (runtime access goes through the preload maka bridge); app-shell.tsx is 1810 lines; maka-tokens.css is 73KB; Badge moved to primitives/ via refactor(ui): converge unmanaged design specs (line-height, font-weight, letter-spacing, …) #520 PR9; buttonVariants lives in ui.tsx; the preload exposes the maka namespace with <domain>:<action> IPC channels.
No build/test run — pure docs PR, no code change.

User-facing impact

None. Docs only.

Reviewer notes

Three commits, one per README, per the "smallest independently-revertible intent" commit unit — each README is self-contained; reverting one leaves the other two usable.
Transitional surfaces are described with direction + end state only — no TODOs, no progress, no time-sensitive content (that stays in issues/PRs). The READMEs are meant not to rot.
design-system.md / frontend-css-governance.md references note they're being refreshed by @jackwener; code + contract tests are the source of truth until then.

Checklist

Scope matches the PR title and excludes unrelated changes
Verification lists commands/results, or explains why they were not run
User-facing impact, docs, changelog, migrations, and breaking changes are noted, or marked none
Risk, rollback, or review focus is called out for non-trivial changes
UI changes include screenshots/video, or explain why not applicable (N/A: docs only)

Target-oriented README for the shared UI package: four export surfaces (primitives / ui.tsx / top-level features / components.tsx), the off-barrel convention, the data-slot hook rule with its exceptions, where new code goes, and the ui.tsx→primitives convergence direction. Transitional surfaces are marked with direction + end state, not TODOs.

Target-oriented READMEs for the Electron app shell and its renderer: the main/preload/renderer split, the main naming convention, the three-pattern IPC contract and the registerIpc() registration step, the actual main.ts startup order, the renderer AppShell + app-shell-<scope>-<action> split, the styles/tokens layout (with the --foreground-N wash-vs-text split), and the primitive-first authoring rule. Direction + end state only, no TODOs.

- ui: drop the broken @maka/ui/icons ProviderLogo example (it lives in the renderer); note icons re-exports Lucide symbols; use markerVariants as a real off-barrel example instead of the zero-consumer LiveIndicator; clarify 'runtime consumer' (preload imports types). - renderer: describe AppShell slices as app-shell-* one-concern modules (not a strict two-segment rule several existing slices violate); make the reference-shell.css breadcrumb point at the file's own header. - desktop: fix startup order (window created early, background startup concurrent, handlers before renderer entry that prefetches pre-mount); route main→renderer push through safeSendToRenderer (raw webContents.send throws on destroyed windows); add src/global.d.ts to the new-IPC steps.

- desktop: window is created hidden, revealed after first AppShell paint (notifyRendererReady gate), not 'preload skeleton shows within ms'; drop the false 'background mutations always push via channels, UI converges lazily' invariant (interrupted-session recovery doesn't emit). - ui: scope the off-barrel 'don't re-export' rule to single in-package consumers with no cross-package consumer (previewVariants is re-exported for exactly that cross-package reason), resolving the contradiction with the promotion rule.

@theme

- desktop/renderer: window reveal has a fallback timer, and main.tsx's onboarding prefetch can time out to a fail-soft loading state — stop claiming 'only after first paint' / 'never sees skeleton' / 'no loading flash' as absolute paths. - renderer: maka-tokens.css is the main token source, but a few @theme Tailwind-bridge values (e.g. --shadow-maka-panel) live in styles.css and are contract-pinned there — document the exception instead of claiming a single source. - ui: clarify 'model-provider brand logos' (renderer settings/provider-*); bot-provider logos are in @maka/ui's bot-brand-logo.

- renderer: document the contract-pinned index.html inline .maka-preload skeleton (hardcoded colors, no CSS vars — maka-tokens.css hasn't loaded yet) as the narrow exception to 'styles.css is the only CSS entry'. - ui: resolve the barrel-rule contradiction — new feature components re-export from components.tsx, but only reach index.ts when they have a second or cross-package consumer (primitives are always re-exported).

…components.tsx) index.ts does 'export * from ./components.js', so re-exporting a feature component from components.tsx already puts it on the package barrel — there is no separate 'add to index.ts later' stage. Rule now: relative import while single in-package consumer; re-export from components.tsx (barrel follows automatically) once a second or cross-package consumer appears.

@theme

The @theme Tailwind bridge is split: most aliases (color/typography/spacing/ radius) live in maka-tokens.css, a few values (e.g. --shadow-maka-panel) in styles.css — both contract-pinned, so check which file owns a value before moving it. /* local: ... */ is the rule for new component-local vars; existing ones don't all carry it yet.

@theme

…split) Both maka-tokens.css and styles.css carry an @theme inline block, and their color aliases overlap (--color-background/accent/muted appear in both); styles.css also carries the typography/line-height/font-weight/tracking/ spacing/radius/shadow bridges. Each value's home is contract-pinned (spacing/letter-spacing/foreground-tier contracts), so stop describing it as a clean split and point to the owning contract instead.

@theme

- ui: barrel promotion is cross-package consumer or explicit public-API need, not 'second in-package consumer' (attachment-file-card has two in-package consumers but stays off-barrel); remove the markerVariants example that implied otherwise. - renderer: maka-tokens.css tail is a large recipe section (base/utilities/ recipes/animations), not 'a few fallbacks'; the @theme bridge overlap is concrete (--color-muted maps to --foreground-5 in styles.css but --muted in maka-tokens.css); only some bridge values are contract-pinned (spacing/letter-spacing/foreground-tier), overlapping color aliases are not — don't claim 'each' is pinned.

- renderer: stop claiming overlapping color aliases have no contract pin — some do (--color-control in styles.css via design-system-governance-406; --color-muted-foreground in maka-tokens.css via foreground-tier); only some (e.g. --color-background/accent/muted) are unpinned. - desktop: narrow the safe-send claim — the contract test scans a fixed file list for direct mainWindow.webContents.send forms; new *-ipc-main.ts files aren't auto-covered, so route through the guard in every new file. - ui: sync the index.ts and chat.tsx LiveIndicator comments to the README barrel rule (cross-package consumer or explicit public-API need, not a second in-package consumer; attachment-file-card precedent), so the README is the single source of the promotion rule.

…irement) The synced comments still described chat call sites and the tool stream as consumers, but #712 retired streamVariants/LiveIndicator from the tool body — they have no production consumer now (chat-stream-cascade-contract pins it). State that in the comments, and drop the contradictory 'LiveIndicator exported only on cross-package consumer' line so the promotion rule is stated once (cross-package consumer or explicit public-API need) and points to README.

…owner The barrel promotion rule is volatile when duplicated into inline source comments (consumer lists drift as symbols retire — e.g. streamVariants/ LiveIndicator in #712). Reverting the index.ts/chat.tsx comment edits keeps this PR docs-only and makes packages/ui/README.md the single source of truth (the README now says so explicitly). Cleaning up the stale source comments / dead symbols is a separate change.

Round 14 review: 'revert + README says comments may lag' still left the stale 'second consumer' / streamVariants/LiveIndicator consumer lists in the source comments, so the conflict source survived. Real root correction: the inline comments no longer re-derive the promotion rule or track consumers (that list drifts as symbols retire, e.g. #712) — they keep their local implementation intent and point at packages/ui/README.md for the rule. README stays the single owner; dead-symbol cleanup stays a separate change.

Round 15 found the prior root correction only covered 2 of the consumer/ promotion comment blocks; markerVariants/TextShimmer/toolVariants/previewVariants still re-derived the rule or tracked consumers, and streamVariants/LiveIndicator still assumed a call site that #712 removed. Exhaustively replace every such block: keep local implementation intent + a short pointer to the README, drop all consumer counts and promotion derivations. Also drop the README's 'inline comments may lag' line (no longer needed once the comments don't re-derive).

16 rounds of review showed cleaning inline source comments is a bottomless local patch: chat.tsx has many historical consumer/call-site mentions (incl. #712-retired streamVariants dead-code notes), and each fix surfaced an adjacent one. Root correction per receiving-code-review: keep this PR docs-only (3 READMEs), revert the index.ts/chat.tsx comment edits to main, and make packages/ui/README.md the single owner of the barrel promotion rule. Source-comment cleanup and dead- symbol removal are separate changes.

Astro-Han · 2026-07-11T16:21:49Z

Summary

Add target-oriented architecture READMEs for the three frontend surfaces — packages/ui, the renderer, and the desktop app shell — to guide agents through the React + BaseUI + shadcn + Tailwind convergence.

Why

The convergence to React + BaseUI + shadcn + Tailwind is mostly in place, but the per-surface architecture lives nowhere locally. Agents entering packages/ui or the renderer have no map for the export layers, the app-shell split, the styles/tokens layout, or which transitional surfaces to retire. docs/ has the authoritative design-system contract (being refreshed by @jackwener) but nothing at the module level.

Direct docs request; no tracking issue.

Scope

Changed:

packages/ui/README.md — four export surfaces (primitives / ui.tsx / top-level features / components.tsx), the off-barrel convention, where new code goes, the ui.tsx→primitives convergence direction.
apps/desktop/src/renderer/README.md — the AppShell + app-shell-<scope>-<action> split, the styles/tokens layout (maka-tokens.css, reference-shell.css, styles/*.css), the primitive-first authoring rule, the transitional surfaces.
apps/desktop/README.md — the main/preload/renderer split, the main naming convention (*-ipc-main / *-main / *-guard), the IPC contract, the data flow.

Not included:

No code changes (pure docs).
No edits to docs/design-system.md or docs/frontend-css-governance.md (being refreshed by @jackwener; the READMEs only reference them).
No new docs/ files — the per-surface READMEs go in place, not in docs/.

Verification

Verified all 13 paths referenced in the READMEs exist.
Cross-checked facts against code: @maka/ui is consumed only by desktop; the main.tsx→app.tsx→AppShell chain; the renderer only import types from @maka/runtime / @maka/storage (runtime access goes through the preload maka bridge); app-shell.tsx is 1810 lines; maka-tokens.css is 73KB; Badge moved to primitives/ via refactor(ui): converge unmanaged design specs (line-height, font-weight, letter-spacing, …) #520 PR9; buttonVariants lives in ui.tsx; the preload exposes the maka namespace with <domain>:<action> IPC channels.
No build/test run — pure docs PR, no code change.

User-facing impact

None. Docs only.

Reviewer notes

Three commits, one per README, per the "smallest independently-revertible intent" commit unit — each README is self-contained; reverting one leaves the other two usable.
Transitional surfaces are described with direction + end state only — no TODOs, no progress, no time-sensitive content (that stays in issues/PRs). The READMEs are meant not to rot.
design-system.md / frontend-css-governance.md references note they're being refreshed by @jackwener; code + contract tests are the source of truth until then.

Checklist

Scope matches the PR title and excludes unrelated changes
Verification lists commands/results, or explains why they were not run
User-facing impact, docs, changelog, migrations, and breaking changes are noted, or marked none
Risk, rollback, or review focus is called out for non-trivial changes
UI changes include screenshots/video, or explain why not applicable (N/A: docs only)

Target-oriented README for the shared UI package: four export surfaces (primitives / ui.tsx / top-level features / components.tsx), the off-barrel convention, the data-slot hook rule with its exceptions, where new code goes, and the ui.tsx→primitives convergence direction. Transitional surfaces are marked with direction + end state, not TODOs.

Target-oriented READMEs for the Electron app shell and its renderer: the main/preload/renderer split, the main naming convention, the three-pattern IPC contract and the registerIpc() registration step, the actual main.ts startup order, the renderer AppShell + app-shell-<scope>-<action> split, the styles/tokens layout (with the --foreground-N wash-vs-text split), and the primitive-first authoring rule. Direction + end state only, no TODOs.

- ui: drop the broken @maka/ui/icons ProviderLogo example (it lives in the renderer); note icons re-exports Lucide symbols; use markerVariants as a real off-barrel example instead of the zero-consumer LiveIndicator; clarify 'runtime consumer' (preload imports types). - renderer: describe AppShell slices as app-shell-* one-concern modules (not a strict two-segment rule several existing slices violate); make the reference-shell.css breadcrumb point at the file's own header. - desktop: fix startup order (window created early, background startup concurrent, handlers before renderer entry that prefetches pre-mount); route main→renderer push through safeSendToRenderer (raw webContents.send throws on destroyed windows); add src/global.d.ts to the new-IPC steps.

- desktop: window is created hidden, revealed after first AppShell paint (notifyRendererReady gate), not 'preload skeleton shows within ms'; drop the false 'background mutations always push via channels, UI converges lazily' invariant (interrupted-session recovery doesn't emit). - ui: scope the off-barrel 'don't re-export' rule to single in-package consumers with no cross-package consumer (previewVariants is re-exported for exactly that cross-package reason), resolving the contradiction with the promotion rule.

@theme

- desktop/renderer: window reveal has a fallback timer, and main.tsx's onboarding prefetch can time out to a fail-soft loading state — stop claiming 'only after first paint' / 'never sees skeleton' / 'no loading flash' as absolute paths. - renderer: maka-tokens.css is the main token source, but a few @theme Tailwind-bridge values (e.g. --shadow-maka-panel) live in styles.css and are contract-pinned there — document the exception instead of claiming a single source. - ui: clarify 'model-provider brand logos' (renderer settings/provider-*); bot-provider logos are in @maka/ui's bot-brand-logo.

- renderer: document the contract-pinned index.html inline .maka-preload skeleton (hardcoded colors, no CSS vars — maka-tokens.css hasn't loaded yet) as the narrow exception to 'styles.css is the only CSS entry'. - ui: resolve the barrel-rule contradiction — new feature components re-export from components.tsx, but only reach index.ts when they have a second or cross-package consumer (primitives are always re-exported).

…components.tsx) index.ts does 'export * from ./components.js', so re-exporting a feature component from components.tsx already puts it on the package barrel — there is no separate 'add to index.ts later' stage. Rule now: relative import while single in-package consumer; re-export from components.tsx (barrel follows automatically) once a second or cross-package consumer appears.

@theme

The @theme Tailwind bridge is split: most aliases (color/typography/spacing/ radius) live in maka-tokens.css, a few values (e.g. --shadow-maka-panel) in styles.css — both contract-pinned, so check which file owns a value before moving it. /* local: ... */ is the rule for new component-local vars; existing ones don't all carry it yet.

@theme

…split) Both maka-tokens.css and styles.css carry an @theme inline block, and their color aliases overlap (--color-background/accent/muted appear in both); styles.css also carries the typography/line-height/font-weight/tracking/ spacing/radius/shadow bridges. Each value's home is contract-pinned (spacing/letter-spacing/foreground-tier contracts), so stop describing it as a clean split and point to the owning contract instead.

@theme

- ui: barrel promotion is cross-package consumer or explicit public-API need, not 'second in-package consumer' (attachment-file-card has two in-package consumers but stays off-barrel); remove the markerVariants example that implied otherwise. - renderer: maka-tokens.css tail is a large recipe section (base/utilities/ recipes/animations), not 'a few fallbacks'; the @theme bridge overlap is concrete (--color-muted maps to --foreground-5 in styles.css but --muted in maka-tokens.css); only some bridge values are contract-pinned (spacing/letter-spacing/foreground-tier), overlapping color aliases are not — don't claim 'each' is pinned.

- renderer: stop claiming overlapping color aliases have no contract pin — some do (--color-control in styles.css via design-system-governance-406; --color-muted-foreground in maka-tokens.css via foreground-tier); only some (e.g. --color-background/accent/muted) are unpinned. - desktop: narrow the safe-send claim — the contract test scans a fixed file list for direct mainWindow.webContents.send forms; new *-ipc-main.ts files aren't auto-covered, so route through the guard in every new file. - ui: sync the index.ts and chat.tsx LiveIndicator comments to the README barrel rule (cross-package consumer or explicit public-API need, not a second in-package consumer; attachment-file-card precedent), so the README is the single source of the promotion rule.

…irement) The synced comments still described chat call sites and the tool stream as consumers, but #712 retired streamVariants/LiveIndicator from the tool body — they have no production consumer now (chat-stream-cascade-contract pins it). State that in the comments, and drop the contradictory 'LiveIndicator exported only on cross-package consumer' line so the promotion rule is stated once (cross-package consumer or explicit public-API need) and points to README.

…owner The barrel promotion rule is volatile when duplicated into inline source comments (consumer lists drift as symbols retire — e.g. streamVariants/ LiveIndicator in #712). Reverting the index.ts/chat.tsx comment edits keeps this PR docs-only and makes packages/ui/README.md the single source of truth (the README now says so explicitly). Cleaning up the stale source comments / dead symbols is a separate change.

Round 14 review: 'revert + README says comments may lag' still left the stale 'second consumer' / streamVariants/LiveIndicator consumer lists in the source comments, so the conflict source survived. Real root correction: the inline comments no longer re-derive the promotion rule or track consumers (that list drifts as symbols retire, e.g. #712) — they keep their local implementation intent and point at packages/ui/README.md for the rule. README stays the single owner; dead-symbol cleanup stays a separate change.

Round 15 found the prior root correction only covered 2 of the consumer/ promotion comment blocks; markerVariants/TextShimmer/toolVariants/previewVariants still re-derived the rule or tracked consumers, and streamVariants/LiveIndicator still assumed a call site that #712 removed. Exhaustively replace every such block: keep local implementation intent + a short pointer to the README, drop all consumer counts and promotion derivations. Also drop the README's 'inline comments may lag' line (no longer needed once the comments don't re-derive).

16 rounds of review showed cleaning inline source comments is a bottomless local patch: chat.tsx has many historical consumer/call-site mentions (incl. #712-retired streamVariants dead-code notes), and each fix surfaced an adjacent one. Root correction per receiving-code-review: keep this PR docs-only (3 READMEs), revert the index.ts/chat.tsx comment edits to main, and make packages/ui/README.md the single owner of the barrel promotion rule. Source-comment cleanup and dead- symbol removal are separate changes.

Astro-Han · 2026-07-11T16:21:49Z

Summary

Add target-oriented architecture READMEs for the three frontend surfaces — packages/ui, the renderer, and the desktop app shell — to guide agents through the React + BaseUI + shadcn + Tailwind convergence.

Why

The convergence to React + BaseUI + shadcn + Tailwind is mostly in place, but the per-surface architecture lives nowhere locally. Agents entering packages/ui or the renderer have no map for the export layers, the app-shell split, the styles/tokens layout, or which transitional surfaces to retire. docs/ has the authoritative design-system contract (being refreshed by @jackwener) but nothing at the module level.

Direct docs request; no tracking issue.

Scope

Changed:

packages/ui/README.md — four export surfaces (primitives / ui.tsx / top-level features / components.tsx), the off-barrel convention, where new code goes, the ui.tsx→primitives convergence direction.
apps/desktop/src/renderer/README.md — the AppShell + app-shell-<scope>-<action> split, the styles/tokens layout (maka-tokens.css, reference-shell.css, styles/*.css), the primitive-first authoring rule, the transitional surfaces.
apps/desktop/README.md — the main/preload/renderer split, the main naming convention (*-ipc-main / *-main / *-guard), the IPC contract, the data flow.

Not included:

No code changes (pure docs).
No edits to docs/design-system.md or docs/frontend-css-governance.md (being refreshed by @jackwener; the READMEs only reference them).
No new docs/ files — the per-surface READMEs go in place, not in docs/.

Verification

Verified all 13 paths referenced in the READMEs exist.
Cross-checked facts against code: @maka/ui is consumed only by desktop; the main.tsx→app.tsx→AppShell chain; the renderer only import types from @maka/runtime / @maka/storage (runtime access goes through the preload maka bridge); app-shell.tsx is 1810 lines; maka-tokens.css is 73KB; Badge moved to primitives/ via refactor(ui): converge unmanaged design specs (line-height, font-weight, letter-spacing, …) #520 PR9; buttonVariants lives in ui.tsx; the preload exposes the maka namespace with <domain>:<action> IPC channels.
No build/test run — pure docs PR, no code change.

User-facing impact

None. Docs only.

Reviewer notes

Three commits, one per README, per the "smallest independently-revertible intent" commit unit — each README is self-contained; reverting one leaves the other two usable.
Transitional surfaces are described with direction + end state only — no TODOs, no progress, no time-sensitive content (that stays in issues/PRs). The READMEs are meant not to rot.
design-system.md / frontend-css-governance.md references note they're being refreshed by @jackwener; code + contract tests are the source of truth until then.

Checklist

Scope matches the PR title and excludes unrelated changes
Verification lists commands/results, or explains why they were not run
User-facing impact, docs, changelog, migrations, and breaking changes are noted, or marked none
Risk, rollback, or review focus is called out for non-trivial changes
UI changes include screenshots/video, or explain why not applicable (N/A: docs only)

Target-oriented README for the shared UI package: four export surfaces (primitives / ui.tsx / top-level features / components.tsx), the off-barrel convention, the data-slot hook rule with its exceptions, where new code goes, and the ui.tsx→primitives convergence direction. Transitional surfaces are marked with direction + end state, not TODOs.

Target-oriented READMEs for the Electron app shell and its renderer: the main/preload/renderer split, the main naming convention, the three-pattern IPC contract and the registerIpc() registration step, the actual main.ts startup order, the renderer AppShell + app-shell-<scope>-<action> split, the styles/tokens layout (with the --foreground-N wash-vs-text split), and the primitive-first authoring rule. Direction + end state only, no TODOs.

- ui: drop the broken @maka/ui/icons ProviderLogo example (it lives in the renderer); note icons re-exports Lucide symbols; use markerVariants as a real off-barrel example instead of the zero-consumer LiveIndicator; clarify 'runtime consumer' (preload imports types). - renderer: describe AppShell slices as app-shell-* one-concern modules (not a strict two-segment rule several existing slices violate); make the reference-shell.css breadcrumb point at the file's own header. - desktop: fix startup order (window created early, background startup concurrent, handlers before renderer entry that prefetches pre-mount); route main→renderer push through safeSendToRenderer (raw webContents.send throws on destroyed windows); add src/global.d.ts to the new-IPC steps.

- desktop: window is created hidden, revealed after first AppShell paint (notifyRendererReady gate), not 'preload skeleton shows within ms'; drop the false 'background mutations always push via channels, UI converges lazily' invariant (interrupted-session recovery doesn't emit). - ui: scope the off-barrel 'don't re-export' rule to single in-package consumers with no cross-package consumer (previewVariants is re-exported for exactly that cross-package reason), resolving the contradiction with the promotion rule.

@theme

- desktop/renderer: window reveal has a fallback timer, and main.tsx's onboarding prefetch can time out to a fail-soft loading state — stop claiming 'only after first paint' / 'never sees skeleton' / 'no loading flash' as absolute paths. - renderer: maka-tokens.css is the main token source, but a few @theme Tailwind-bridge values (e.g. --shadow-maka-panel) live in styles.css and are contract-pinned there — document the exception instead of claiming a single source. - ui: clarify 'model-provider brand logos' (renderer settings/provider-*); bot-provider logos are in @maka/ui's bot-brand-logo.

- renderer: document the contract-pinned index.html inline .maka-preload skeleton (hardcoded colors, no CSS vars — maka-tokens.css hasn't loaded yet) as the narrow exception to 'styles.css is the only CSS entry'. - ui: resolve the barrel-rule contradiction — new feature components re-export from components.tsx, but only reach index.ts when they have a second or cross-package consumer (primitives are always re-exported).

…components.tsx) index.ts does 'export * from ./components.js', so re-exporting a feature component from components.tsx already puts it on the package barrel — there is no separate 'add to index.ts later' stage. Rule now: relative import while single in-package consumer; re-export from components.tsx (barrel follows automatically) once a second or cross-package consumer appears.

@theme

The @theme Tailwind bridge is split: most aliases (color/typography/spacing/ radius) live in maka-tokens.css, a few values (e.g. --shadow-maka-panel) in styles.css — both contract-pinned, so check which file owns a value before moving it. /* local: ... */ is the rule for new component-local vars; existing ones don't all carry it yet.

@theme

…split) Both maka-tokens.css and styles.css carry an @theme inline block, and their color aliases overlap (--color-background/accent/muted appear in both); styles.css also carries the typography/line-height/font-weight/tracking/ spacing/radius/shadow bridges. Each value's home is contract-pinned (spacing/letter-spacing/foreground-tier contracts), so stop describing it as a clean split and point to the owning contract instead.

@theme

- ui: barrel promotion is cross-package consumer or explicit public-API need, not 'second in-package consumer' (attachment-file-card has two in-package consumers but stays off-barrel); remove the markerVariants example that implied otherwise. - renderer: maka-tokens.css tail is a large recipe section (base/utilities/ recipes/animations), not 'a few fallbacks'; the @theme bridge overlap is concrete (--color-muted maps to --foreground-5 in styles.css but --muted in maka-tokens.css); only some bridge values are contract-pinned (spacing/letter-spacing/foreground-tier), overlapping color aliases are not — don't claim 'each' is pinned.

- renderer: stop claiming overlapping color aliases have no contract pin — some do (--color-control in styles.css via design-system-governance-406; --color-muted-foreground in maka-tokens.css via foreground-tier); only some (e.g. --color-background/accent/muted) are unpinned. - desktop: narrow the safe-send claim — the contract test scans a fixed file list for direct mainWindow.webContents.send forms; new *-ipc-main.ts files aren't auto-covered, so route through the guard in every new file. - ui: sync the index.ts and chat.tsx LiveIndicator comments to the README barrel rule (cross-package consumer or explicit public-API need, not a second in-package consumer; attachment-file-card precedent), so the README is the single source of the promotion rule.

…irement) The synced comments still described chat call sites and the tool stream as consumers, but #712 retired streamVariants/LiveIndicator from the tool body — they have no production consumer now (chat-stream-cascade-contract pins it). State that in the comments, and drop the contradictory 'LiveIndicator exported only on cross-package consumer' line so the promotion rule is stated once (cross-package consumer or explicit public-API need) and points to README.

…owner The barrel promotion rule is volatile when duplicated into inline source comments (consumer lists drift as symbols retire — e.g. streamVariants/ LiveIndicator in #712). Reverting the index.ts/chat.tsx comment edits keeps this PR docs-only and makes packages/ui/README.md the single source of truth (the README now says so explicitly). Cleaning up the stale source comments / dead symbols is a separate change.

Round 14 review: 'revert + README says comments may lag' still left the stale 'second consumer' / streamVariants/LiveIndicator consumer lists in the source comments, so the conflict source survived. Real root correction: the inline comments no longer re-derive the promotion rule or track consumers (that list drifts as symbols retire, e.g. #712) — they keep their local implementation intent and point at packages/ui/README.md for the rule. README stays the single owner; dead-symbol cleanup stays a separate change.

Round 15 found the prior root correction only covered 2 of the consumer/ promotion comment blocks; markerVariants/TextShimmer/toolVariants/previewVariants still re-derived the rule or tracked consumers, and streamVariants/LiveIndicator still assumed a call site that #712 removed. Exhaustively replace every such block: keep local implementation intent + a short pointer to the README, drop all consumer counts and promotion derivations. Also drop the README's 'inline comments may lag' line (no longer needed once the comments don't re-derive).

16 rounds of review showed cleaning inline source comments is a bottomless local patch: chat.tsx has many historical consumer/call-site mentions (incl. #712-retired streamVariants dead-code notes), and each fix surfaced an adjacent one. Root correction per receiving-code-review: keep this PR docs-only (3 READMEs), revert the index.ts/chat.tsx comment edits to main, and make packages/ui/README.md the single owner of the barrel promotion rule. Source-comment cleanup and dead- symbol removal are separate changes.

Astro-Han · 2026-07-11T16:21:49Z

Summary

Add target-oriented architecture READMEs for the three frontend surfaces — packages/ui, the renderer, and the desktop app shell — to guide agents through the React + BaseUI + shadcn + Tailwind convergence.

Why

The convergence to React + BaseUI + shadcn + Tailwind is mostly in place, but the per-surface architecture lives nowhere locally. Agents entering packages/ui or the renderer have no map for the export layers, the app-shell split, the styles/tokens layout, or which transitional surfaces to retire. docs/ has the authoritative design-system contract (being refreshed by @jackwener) but nothing at the module level.

Direct docs request; no tracking issue.

Scope

Changed:

packages/ui/README.md — four export surfaces (primitives / ui.tsx / top-level features / components.tsx), the off-barrel convention, where new code goes, the ui.tsx→primitives convergence direction.
apps/desktop/src/renderer/README.md — the AppShell + app-shell-<scope>-<action> split, the styles/tokens layout (maka-tokens.css, reference-shell.css, styles/*.css), the primitive-first authoring rule, the transitional surfaces.
apps/desktop/README.md — the main/preload/renderer split, the main naming convention (*-ipc-main / *-main / *-guard), the IPC contract, the data flow.

Not included:

No code changes (pure docs).
No edits to docs/design-system.md or docs/frontend-css-governance.md (being refreshed by @jackwener; the READMEs only reference them).
No new docs/ files — the per-surface READMEs go in place, not in docs/.

Verification

Verified all 13 paths referenced in the READMEs exist.
Cross-checked facts against code: @maka/ui is consumed only by desktop; the main.tsx→app.tsx→AppShell chain; the renderer only import types from @maka/runtime / @maka/storage (runtime access goes through the preload maka bridge); app-shell.tsx is 1810 lines; maka-tokens.css is 73KB; Badge moved to primitives/ via refactor(ui): converge unmanaged design specs (line-height, font-weight, letter-spacing, …) #520 PR9; buttonVariants lives in ui.tsx; the preload exposes the maka namespace with <domain>:<action> IPC channels.
No build/test run — pure docs PR, no code change.

User-facing impact

None. Docs only.

Reviewer notes

Three commits, one per README, per the "smallest independently-revertible intent" commit unit — each README is self-contained; reverting one leaves the other two usable.
Transitional surfaces are described with direction + end state only — no TODOs, no progress, no time-sensitive content (that stays in issues/PRs). The READMEs are meant not to rot.
design-system.md / frontend-css-governance.md references note they're being refreshed by @jackwener; code + contract tests are the source of truth until then.

Checklist

Scope matches the PR title and excludes unrelated changes
Verification lists commands/results, or explains why they were not run
User-facing impact, docs, changelog, migrations, and breaking changes are noted, or marked none
Risk, rollback, or review focus is called out for non-trivial changes
UI changes include screenshots/video, or explain why not applicable (N/A: docs only)

Target-oriented README for the shared UI package: four export surfaces (primitives / ui.tsx / top-level features / components.tsx), the off-barrel convention, the data-slot hook rule with its exceptions, where new code goes, and the ui.tsx→primitives convergence direction. Transitional surfaces are marked with direction + end state, not TODOs.

Target-oriented READMEs for the Electron app shell and its renderer: the main/preload/renderer split, the main naming convention, the three-pattern IPC contract and the registerIpc() registration step, the actual main.ts startup order, the renderer AppShell + app-shell-<scope>-<action> split, the styles/tokens layout (with the --foreground-N wash-vs-text split), and the primitive-first authoring rule. Direction + end state only, no TODOs.

- ui: drop the broken @maka/ui/icons ProviderLogo example (it lives in the renderer); note icons re-exports Lucide symbols; use markerVariants as a real off-barrel example instead of the zero-consumer LiveIndicator; clarify 'runtime consumer' (preload imports types). - renderer: describe AppShell slices as app-shell-* one-concern modules (not a strict two-segment rule several existing slices violate); make the reference-shell.css breadcrumb point at the file's own header. - desktop: fix startup order (window created early, background startup concurrent, handlers before renderer entry that prefetches pre-mount); route main→renderer push through safeSendToRenderer (raw webContents.send throws on destroyed windows); add src/global.d.ts to the new-IPC steps.

- desktop: window is created hidden, revealed after first AppShell paint (notifyRendererReady gate), not 'preload skeleton shows within ms'; drop the false 'background mutations always push via channels, UI converges lazily' invariant (interrupted-session recovery doesn't emit). - ui: scope the off-barrel 'don't re-export' rule to single in-package consumers with no cross-package consumer (previewVariants is re-exported for exactly that cross-package reason), resolving the contradiction with the promotion rule.

@theme

- desktop/renderer: window reveal has a fallback timer, and main.tsx's onboarding prefetch can time out to a fail-soft loading state — stop claiming 'only after first paint' / 'never sees skeleton' / 'no loading flash' as absolute paths. - renderer: maka-tokens.css is the main token source, but a few @theme Tailwind-bridge values (e.g. --shadow-maka-panel) live in styles.css and are contract-pinned there — document the exception instead of claiming a single source. - ui: clarify 'model-provider brand logos' (renderer settings/provider-*); bot-provider logos are in @maka/ui's bot-brand-logo.

- renderer: document the contract-pinned index.html inline .maka-preload skeleton (hardcoded colors, no CSS vars — maka-tokens.css hasn't loaded yet) as the narrow exception to 'styles.css is the only CSS entry'. - ui: resolve the barrel-rule contradiction — new feature components re-export from components.tsx, but only reach index.ts when they have a second or cross-package consumer (primitives are always re-exported).

…components.tsx) index.ts does 'export * from ./components.js', so re-exporting a feature component from components.tsx already puts it on the package barrel — there is no separate 'add to index.ts later' stage. Rule now: relative import while single in-package consumer; re-export from components.tsx (barrel follows automatically) once a second or cross-package consumer appears.

@theme

The @theme Tailwind bridge is split: most aliases (color/typography/spacing/ radius) live in maka-tokens.css, a few values (e.g. --shadow-maka-panel) in styles.css — both contract-pinned, so check which file owns a value before moving it. /* local: ... */ is the rule for new component-local vars; existing ones don't all carry it yet.

@theme

…split) Both maka-tokens.css and styles.css carry an @theme inline block, and their color aliases overlap (--color-background/accent/muted appear in both); styles.css also carries the typography/line-height/font-weight/tracking/ spacing/radius/shadow bridges. Each value's home is contract-pinned (spacing/letter-spacing/foreground-tier contracts), so stop describing it as a clean split and point to the owning contract instead.

@theme

- ui: barrel promotion is cross-package consumer or explicit public-API need, not 'second in-package consumer' (attachment-file-card has two in-package consumers but stays off-barrel); remove the markerVariants example that implied otherwise. - renderer: maka-tokens.css tail is a large recipe section (base/utilities/ recipes/animations), not 'a few fallbacks'; the @theme bridge overlap is concrete (--color-muted maps to --foreground-5 in styles.css but --muted in maka-tokens.css); only some bridge values are contract-pinned (spacing/letter-spacing/foreground-tier), overlapping color aliases are not — don't claim 'each' is pinned.

- renderer: stop claiming overlapping color aliases have no contract pin — some do (--color-control in styles.css via design-system-governance-406; --color-muted-foreground in maka-tokens.css via foreground-tier); only some (e.g. --color-background/accent/muted) are unpinned. - desktop: narrow the safe-send claim — the contract test scans a fixed file list for direct mainWindow.webContents.send forms; new *-ipc-main.ts files aren't auto-covered, so route through the guard in every new file. - ui: sync the index.ts and chat.tsx LiveIndicator comments to the README barrel rule (cross-package consumer or explicit public-API need, not a second in-package consumer; attachment-file-card precedent), so the README is the single source of the promotion rule.

…irement) The synced comments still described chat call sites and the tool stream as consumers, but #712 retired streamVariants/LiveIndicator from the tool body — they have no production consumer now (chat-stream-cascade-contract pins it). State that in the comments, and drop the contradictory 'LiveIndicator exported only on cross-package consumer' line so the promotion rule is stated once (cross-package consumer or explicit public-API need) and points to README.

…owner The barrel promotion rule is volatile when duplicated into inline source comments (consumer lists drift as symbols retire — e.g. streamVariants/ LiveIndicator in #712). Reverting the index.ts/chat.tsx comment edits keeps this PR docs-only and makes packages/ui/README.md the single source of truth (the README now says so explicitly). Cleaning up the stale source comments / dead symbols is a separate change.

Round 14 review: 'revert + README says comments may lag' still left the stale 'second consumer' / streamVariants/LiveIndicator consumer lists in the source comments, so the conflict source survived. Real root correction: the inline comments no longer re-derive the promotion rule or track consumers (that list drifts as symbols retire, e.g. #712) — they keep their local implementation intent and point at packages/ui/README.md for the rule. README stays the single owner; dead-symbol cleanup stays a separate change.

Round 15 found the prior root correction only covered 2 of the consumer/ promotion comment blocks; markerVariants/TextShimmer/toolVariants/previewVariants still re-derived the rule or tracked consumers, and streamVariants/LiveIndicator still assumed a call site that #712 removed. Exhaustively replace every such block: keep local implementation intent + a short pointer to the README, drop all consumer counts and promotion derivations. Also drop the README's 'inline comments may lag' line (no longer needed once the comments don't re-derive).

16 rounds of review showed cleaning inline source comments is a bottomless local patch: chat.tsx has many historical consumer/call-site mentions (incl. #712-retired streamVariants dead-code notes), and each fix surfaced an adjacent one. Root correction per receiving-code-review: keep this PR docs-only (3 READMEs), revert the index.ts/chat.tsx comment edits to main, and make packages/ui/README.md the single owner of the barrel promotion rule. Source-comment cleanup and dead- symbol removal are separate changes.

Astro-Han · 2026-07-11T16:21:49Z

Summary

Add target-oriented architecture READMEs for the three frontend surfaces — packages/ui, the renderer, and the desktop app shell — to guide agents through the React + BaseUI + shadcn + Tailwind convergence.

Why

The convergence to React + BaseUI + shadcn + Tailwind is mostly in place, but the per-surface architecture lives nowhere locally. Agents entering packages/ui or the renderer have no map for the export layers, the app-shell split, the styles/tokens layout, or which transitional surfaces to retire. docs/ has the authoritative design-system contract (being refreshed by @jackwener) but nothing at the module level.

Direct docs request; no tracking issue.

Scope

Changed:

packages/ui/README.md — four export surfaces (primitives / ui.tsx / top-level features / components.tsx), the off-barrel convention, where new code goes, the ui.tsx→primitives convergence direction.
apps/desktop/src/renderer/README.md — the AppShell + app-shell-<scope>-<action> split, the styles/tokens layout (maka-tokens.css, reference-shell.css, styles/*.css), the primitive-first authoring rule, the transitional surfaces.
apps/desktop/README.md — the main/preload/renderer split, the main naming convention (*-ipc-main / *-main / *-guard), the IPC contract, the data flow.

Not included:

No code changes (pure docs).
No edits to docs/design-system.md or docs/frontend-css-governance.md (being refreshed by @jackwener; the READMEs only reference them).
No new docs/ files — the per-surface READMEs go in place, not in docs/.

Verification

Verified all 13 paths referenced in the READMEs exist.
Cross-checked facts against code: @maka/ui is consumed only by desktop; the main.tsx→app.tsx→AppShell chain; the renderer only import types from @maka/runtime / @maka/storage (runtime access goes through the preload maka bridge); app-shell.tsx is 1810 lines; maka-tokens.css is 73KB; Badge moved to primitives/ via refactor(ui): converge unmanaged design specs (line-height, font-weight, letter-spacing, …) #520 PR9; buttonVariants lives in ui.tsx; the preload exposes the maka namespace with <domain>:<action> IPC channels.
No build/test run — pure docs PR, no code change.

User-facing impact

None. Docs only.

Reviewer notes

Three commits, one per README, per the "smallest independently-revertible intent" commit unit — each README is self-contained; reverting one leaves the other two usable.
Transitional surfaces are described with direction + end state only — no TODOs, no progress, no time-sensitive content (that stays in issues/PRs). The READMEs are meant not to rot.
design-system.md / frontend-css-governance.md references note they're being refreshed by @jackwener; code + contract tests are the source of truth until then.

Checklist

Scope matches the PR title and excludes unrelated changes
Verification lists commands/results, or explains why they were not run
User-facing impact, docs, changelog, migrations, and breaking changes are noted, or marked none
Risk, rollback, or review focus is called out for non-trivial changes
UI changes include screenshots/video, or explain why not applicable (N/A: docs only)

Target-oriented README for the shared UI package: four export surfaces (primitives / ui.tsx / top-level features / components.tsx), the off-barrel convention, the data-slot hook rule with its exceptions, where new code goes, and the ui.tsx→primitives convergence direction. Transitional surfaces are marked with direction + end state, not TODOs.

Target-oriented READMEs for the Electron app shell and its renderer: the main/preload/renderer split, the main naming convention, the three-pattern IPC contract and the registerIpc() registration step, the actual main.ts startup order, the renderer AppShell + app-shell-<scope>-<action> split, the styles/tokens layout (with the --foreground-N wash-vs-text split), and the primitive-first authoring rule. Direction + end state only, no TODOs.

- ui: drop the broken @maka/ui/icons ProviderLogo example (it lives in the renderer); note icons re-exports Lucide symbols; use markerVariants as a real off-barrel example instead of the zero-consumer LiveIndicator; clarify 'runtime consumer' (preload imports types). - renderer: describe AppShell slices as app-shell-* one-concern modules (not a strict two-segment rule several existing slices violate); make the reference-shell.css breadcrumb point at the file's own header. - desktop: fix startup order (window created early, background startup concurrent, handlers before renderer entry that prefetches pre-mount); route main→renderer push through safeSendToRenderer (raw webContents.send throws on destroyed windows); add src/global.d.ts to the new-IPC steps.

- desktop: window is created hidden, revealed after first AppShell paint (notifyRendererReady gate), not 'preload skeleton shows within ms'; drop the false 'background mutations always push via channels, UI converges lazily' invariant (interrupted-session recovery doesn't emit). - ui: scope the off-barrel 'don't re-export' rule to single in-package consumers with no cross-package consumer (previewVariants is re-exported for exactly that cross-package reason), resolving the contradiction with the promotion rule.

@theme

- desktop/renderer: window reveal has a fallback timer, and main.tsx's onboarding prefetch can time out to a fail-soft loading state — stop claiming 'only after first paint' / 'never sees skeleton' / 'no loading flash' as absolute paths. - renderer: maka-tokens.css is the main token source, but a few @theme Tailwind-bridge values (e.g. --shadow-maka-panel) live in styles.css and are contract-pinned there — document the exception instead of claiming a single source. - ui: clarify 'model-provider brand logos' (renderer settings/provider-*); bot-provider logos are in @maka/ui's bot-brand-logo.

- renderer: document the contract-pinned index.html inline .maka-preload skeleton (hardcoded colors, no CSS vars — maka-tokens.css hasn't loaded yet) as the narrow exception to 'styles.css is the only CSS entry'. - ui: resolve the barrel-rule contradiction — new feature components re-export from components.tsx, but only reach index.ts when they have a second or cross-package consumer (primitives are always re-exported).

…components.tsx) index.ts does 'export * from ./components.js', so re-exporting a feature component from components.tsx already puts it on the package barrel — there is no separate 'add to index.ts later' stage. Rule now: relative import while single in-package consumer; re-export from components.tsx (barrel follows automatically) once a second or cross-package consumer appears.

@theme

The @theme Tailwind bridge is split: most aliases (color/typography/spacing/ radius) live in maka-tokens.css, a few values (e.g. --shadow-maka-panel) in styles.css — both contract-pinned, so check which file owns a value before moving it. /* local: ... */ is the rule for new component-local vars; existing ones don't all carry it yet.

@theme

…split) Both maka-tokens.css and styles.css carry an @theme inline block, and their color aliases overlap (--color-background/accent/muted appear in both); styles.css also carries the typography/line-height/font-weight/tracking/ spacing/radius/shadow bridges. Each value's home is contract-pinned (spacing/letter-spacing/foreground-tier contracts), so stop describing it as a clean split and point to the owning contract instead.

@theme

- ui: barrel promotion is cross-package consumer or explicit public-API need, not 'second in-package consumer' (attachment-file-card has two in-package consumers but stays off-barrel); remove the markerVariants example that implied otherwise. - renderer: maka-tokens.css tail is a large recipe section (base/utilities/ recipes/animations), not 'a few fallbacks'; the @theme bridge overlap is concrete (--color-muted maps to --foreground-5 in styles.css but --muted in maka-tokens.css); only some bridge values are contract-pinned (spacing/letter-spacing/foreground-tier), overlapping color aliases are not — don't claim 'each' is pinned.

- renderer: stop claiming overlapping color aliases have no contract pin — some do (--color-control in styles.css via design-system-governance-406; --color-muted-foreground in maka-tokens.css via foreground-tier); only some (e.g. --color-background/accent/muted) are unpinned. - desktop: narrow the safe-send claim — the contract test scans a fixed file list for direct mainWindow.webContents.send forms; new *-ipc-main.ts files aren't auto-covered, so route through the guard in every new file. - ui: sync the index.ts and chat.tsx LiveIndicator comments to the README barrel rule (cross-package consumer or explicit public-API need, not a second in-package consumer; attachment-file-card precedent), so the README is the single source of the promotion rule.

…irement) The synced comments still described chat call sites and the tool stream as consumers, but #712 retired streamVariants/LiveIndicator from the tool body — they have no production consumer now (chat-stream-cascade-contract pins it). State that in the comments, and drop the contradictory 'LiveIndicator exported only on cross-package consumer' line so the promotion rule is stated once (cross-package consumer or explicit public-API need) and points to README.

…owner The barrel promotion rule is volatile when duplicated into inline source comments (consumer lists drift as symbols retire — e.g. streamVariants/ LiveIndicator in #712). Reverting the index.ts/chat.tsx comment edits keeps this PR docs-only and makes packages/ui/README.md the single source of truth (the README now says so explicitly). Cleaning up the stale source comments / dead symbols is a separate change.

Round 14 review: 'revert + README says comments may lag' still left the stale 'second consumer' / streamVariants/LiveIndicator consumer lists in the source comments, so the conflict source survived. Real root correction: the inline comments no longer re-derive the promotion rule or track consumers (that list drifts as symbols retire, e.g. #712) — they keep their local implementation intent and point at packages/ui/README.md for the rule. README stays the single owner; dead-symbol cleanup stays a separate change.

Round 15 found the prior root correction only covered 2 of the consumer/ promotion comment blocks; markerVariants/TextShimmer/toolVariants/previewVariants still re-derived the rule or tracked consumers, and streamVariants/LiveIndicator still assumed a call site that #712 removed. Exhaustively replace every such block: keep local implementation intent + a short pointer to the README, drop all consumer counts and promotion derivations. Also drop the README's 'inline comments may lag' line (no longer needed once the comments don't re-derive).

16 rounds of review showed cleaning inline source comments is a bottomless local patch: chat.tsx has many historical consumer/call-site mentions (incl. #712-retired streamVariants dead-code notes), and each fix surfaced an adjacent one. Root correction per receiving-code-review: keep this PR docs-only (3 READMEs), revert the index.ts/chat.tsx comment edits to main, and make packages/ui/README.md the single owner of the barrel promotion rule. Source-comment cleanup and dead- symbol removal are separate changes.

Astro-Han · 2026-07-11T16:21:49Z

Summary

Add target-oriented architecture READMEs for the three frontend surfaces — packages/ui, the renderer, and the desktop app shell — to guide agents through the React + BaseUI + shadcn + Tailwind convergence.

Why

The convergence to React + BaseUI + shadcn + Tailwind is mostly in place, but the per-surface architecture lives nowhere locally. Agents entering packages/ui or the renderer have no map for the export layers, the app-shell split, the styles/tokens layout, or which transitional surfaces to retire. docs/ has the authoritative design-system contract (being refreshed by @jackwener) but nothing at the module level.

Direct docs request; no tracking issue.

Scope

Changed:

packages/ui/README.md — four export surfaces (primitives / ui.tsx / top-level features / components.tsx), the off-barrel convention, where new code goes, the ui.tsx→primitives convergence direction.
apps/desktop/src/renderer/README.md — the AppShell + app-shell-<scope>-<action> split, the styles/tokens layout (maka-tokens.css, reference-shell.css, styles/*.css), the primitive-first authoring rule, the transitional surfaces.
apps/desktop/README.md — the main/preload/renderer split, the main naming convention (*-ipc-main / *-main / *-guard), the IPC contract, the data flow.

Not included:

No code changes (pure docs).
No edits to docs/design-system.md or docs/frontend-css-governance.md (being refreshed by @jackwener; the READMEs only reference them).
No new docs/ files — the per-surface READMEs go in place, not in docs/.

Verification

Verified all 13 paths referenced in the READMEs exist.
Cross-checked facts against code: @maka/ui is consumed only by desktop; the main.tsx→app.tsx→AppShell chain; the renderer only import types from @maka/runtime / @maka/storage (runtime access goes through the preload maka bridge); app-shell.tsx is 1810 lines; maka-tokens.css is 73KB; Badge moved to primitives/ via refactor(ui): converge unmanaged design specs (line-height, font-weight, letter-spacing, …) #520 PR9; buttonVariants lives in ui.tsx; the preload exposes the maka namespace with <domain>:<action> IPC channels.
No build/test run — pure docs PR, no code change.

User-facing impact

None. Docs only.

Reviewer notes

Three commits, one per README, per the "smallest independently-revertible intent" commit unit — each README is self-contained; reverting one leaves the other two usable.
Transitional surfaces are described with direction + end state only — no TODOs, no progress, no time-sensitive content (that stays in issues/PRs). The READMEs are meant not to rot.
design-system.md / frontend-css-governance.md references note they're being refreshed by @jackwener; code + contract tests are the source of truth until then.

Checklist

Scope matches the PR title and excludes unrelated changes
Verification lists commands/results, or explains why they were not run
User-facing impact, docs, changelog, migrations, and breaking changes are noted, or marked none
Risk, rollback, or review focus is called out for non-trivial changes
UI changes include screenshots/video, or explain why not applicable (N/A: docs only)

Target-oriented README for the shared UI package: four export surfaces (primitives / ui.tsx / top-level features / components.tsx), the off-barrel convention, the data-slot hook rule with its exceptions, where new code goes, and the ui.tsx→primitives convergence direction. Transitional surfaces are marked with direction + end state, not TODOs.

Target-oriented READMEs for the Electron app shell and its renderer: the main/preload/renderer split, the main naming convention, the three-pattern IPC contract and the registerIpc() registration step, the actual main.ts startup order, the renderer AppShell + app-shell-<scope>-<action> split, the styles/tokens layout (with the --foreground-N wash-vs-text split), and the primitive-first authoring rule. Direction + end state only, no TODOs.

- ui: drop the broken @maka/ui/icons ProviderLogo example (it lives in the renderer); note icons re-exports Lucide symbols; use markerVariants as a real off-barrel example instead of the zero-consumer LiveIndicator; clarify 'runtime consumer' (preload imports types). - renderer: describe AppShell slices as app-shell-* one-concern modules (not a strict two-segment rule several existing slices violate); make the reference-shell.css breadcrumb point at the file's own header. - desktop: fix startup order (window created early, background startup concurrent, handlers before renderer entry that prefetches pre-mount); route main→renderer push through safeSendToRenderer (raw webContents.send throws on destroyed windows); add src/global.d.ts to the new-IPC steps.

- desktop: window is created hidden, revealed after first AppShell paint (notifyRendererReady gate), not 'preload skeleton shows within ms'; drop the false 'background mutations always push via channels, UI converges lazily' invariant (interrupted-session recovery doesn't emit). - ui: scope the off-barrel 'don't re-export' rule to single in-package consumers with no cross-package consumer (previewVariants is re-exported for exactly that cross-package reason), resolving the contradiction with the promotion rule.

@theme

- desktop/renderer: window reveal has a fallback timer, and main.tsx's onboarding prefetch can time out to a fail-soft loading state — stop claiming 'only after first paint' / 'never sees skeleton' / 'no loading flash' as absolute paths. - renderer: maka-tokens.css is the main token source, but a few @theme Tailwind-bridge values (e.g. --shadow-maka-panel) live in styles.css and are contract-pinned there — document the exception instead of claiming a single source. - ui: clarify 'model-provider brand logos' (renderer settings/provider-*); bot-provider logos are in @maka/ui's bot-brand-logo.

- renderer: document the contract-pinned index.html inline .maka-preload skeleton (hardcoded colors, no CSS vars — maka-tokens.css hasn't loaded yet) as the narrow exception to 'styles.css is the only CSS entry'. - ui: resolve the barrel-rule contradiction — new feature components re-export from components.tsx, but only reach index.ts when they have a second or cross-package consumer (primitives are always re-exported).

…components.tsx) index.ts does 'export * from ./components.js', so re-exporting a feature component from components.tsx already puts it on the package barrel — there is no separate 'add to index.ts later' stage. Rule now: relative import while single in-package consumer; re-export from components.tsx (barrel follows automatically) once a second or cross-package consumer appears.

@theme

The @theme Tailwind bridge is split: most aliases (color/typography/spacing/ radius) live in maka-tokens.css, a few values (e.g. --shadow-maka-panel) in styles.css — both contract-pinned, so check which file owns a value before moving it. /* local: ... */ is the rule for new component-local vars; existing ones don't all carry it yet.

@theme

…split) Both maka-tokens.css and styles.css carry an @theme inline block, and their color aliases overlap (--color-background/accent/muted appear in both); styles.css also carries the typography/line-height/font-weight/tracking/ spacing/radius/shadow bridges. Each value's home is contract-pinned (spacing/letter-spacing/foreground-tier contracts), so stop describing it as a clean split and point to the owning contract instead.

@theme

- ui: barrel promotion is cross-package consumer or explicit public-API need, not 'second in-package consumer' (attachment-file-card has two in-package consumers but stays off-barrel); remove the markerVariants example that implied otherwise. - renderer: maka-tokens.css tail is a large recipe section (base/utilities/ recipes/animations), not 'a few fallbacks'; the @theme bridge overlap is concrete (--color-muted maps to --foreground-5 in styles.css but --muted in maka-tokens.css); only some bridge values are contract-pinned (spacing/letter-spacing/foreground-tier), overlapping color aliases are not — don't claim 'each' is pinned.

- renderer: stop claiming overlapping color aliases have no contract pin — some do (--color-control in styles.css via design-system-governance-406; --color-muted-foreground in maka-tokens.css via foreground-tier); only some (e.g. --color-background/accent/muted) are unpinned. - desktop: narrow the safe-send claim — the contract test scans a fixed file list for direct mainWindow.webContents.send forms; new *-ipc-main.ts files aren't auto-covered, so route through the guard in every new file. - ui: sync the index.ts and chat.tsx LiveIndicator comments to the README barrel rule (cross-package consumer or explicit public-API need, not a second in-package consumer; attachment-file-card precedent), so the README is the single source of the promotion rule.

…irement) The synced comments still described chat call sites and the tool stream as consumers, but #712 retired streamVariants/LiveIndicator from the tool body — they have no production consumer now (chat-stream-cascade-contract pins it). State that in the comments, and drop the contradictory 'LiveIndicator exported only on cross-package consumer' line so the promotion rule is stated once (cross-package consumer or explicit public-API need) and points to README.

…owner The barrel promotion rule is volatile when duplicated into inline source comments (consumer lists drift as symbols retire — e.g. streamVariants/ LiveIndicator in #712). Reverting the index.ts/chat.tsx comment edits keeps this PR docs-only and makes packages/ui/README.md the single source of truth (the README now says so explicitly). Cleaning up the stale source comments / dead symbols is a separate change.

Round 14 review: 'revert + README says comments may lag' still left the stale 'second consumer' / streamVariants/LiveIndicator consumer lists in the source comments, so the conflict source survived. Real root correction: the inline comments no longer re-derive the promotion rule or track consumers (that list drifts as symbols retire, e.g. #712) — they keep their local implementation intent and point at packages/ui/README.md for the rule. README stays the single owner; dead-symbol cleanup stays a separate change.

Round 15 found the prior root correction only covered 2 of the consumer/ promotion comment blocks; markerVariants/TextShimmer/toolVariants/previewVariants still re-derived the rule or tracked consumers, and streamVariants/LiveIndicator still assumed a call site that #712 removed. Exhaustively replace every such block: keep local implementation intent + a short pointer to the README, drop all consumer counts and promotion derivations. Also drop the README's 'inline comments may lag' line (no longer needed once the comments don't re-derive).

16 rounds of review showed cleaning inline source comments is a bottomless local patch: chat.tsx has many historical consumer/call-site mentions (incl. #712-retired streamVariants dead-code notes), and each fix surfaced an adjacent one. Root correction per receiving-code-review: keep this PR docs-only (3 READMEs), revert the index.ts/chat.tsx comment edits to main, and make packages/ui/README.md the single owner of the barrel promotion rule. Source-comment cleanup and dead- symbol removal are separate changes.

Astro-Han mentioned this pull request Jul 11, 2026
fix(runtime): give FormatJson the edit activity kind #726
Merged
5 tasks

Astro-Han force-pushed the docs/frontend-architecture-readmes branch 3 times, most recently from 0442812 to e014ee1Compare July 11, 2026 20:24

Astro-Han added 18 commits July 12, 2026 04:59

docs(ui): add architecture README for @maka/ui
019cb03

docs(desktop): add architecture READMEs for the desktop app and renderer
7183d49

Astro-Han force-pushed the docs/frontend-architecture-readmes branch from 113e3c7 to 66bcf23Compare July 11, 2026 20:59

Astro-Han merged commit 57b73ef into mainJul 11, 2026
3 checks passed

Astro-Han deleted the docs/frontend-architecture-readmes branch July 11, 2026 21:20

Astro-Han mentioned this pull request Jul 12, 2026
RFC: establish repository and documentation ownership boundaries #767
Closed

Astro-Han mentioned this pull request Jul 11, 2026
fix(runtime): give FormatJson the edit activity kind #726
Merged
5 tasks

Astro-Han force-pushed the docs/frontend-architecture-readmes branch 3 times, most recently from 0442812 to e014ee1Compare July 11, 2026 20:24

Astro-Han added 18 commits July 12, 2026 04:59

docs(ui): add architecture README for @maka/ui
019cb03

docs(desktop): add architecture READMEs for the desktop app and renderer
7183d49

Astro-Han force-pushed the docs/frontend-architecture-readmes branch from 113e3c7 to 66bcf23Compare July 11, 2026 20:59

Astro-Han merged commit 57b73ef into mainJul 11, 2026
3 checks passed

Astro-Han deleted the docs/frontend-architecture-readmes branch July 11, 2026 21:20

Astro-Han mentioned this pull request Jul 12, 2026
RFC: establish repository and documentation ownership boundaries #767
Closed

Astro-Han mentioned this pull request Jul 11, 2026
fix(runtime): give FormatJson the edit activity kind #726
Merged
5 tasks

Astro-Han force-pushed the docs/frontend-architecture-readmes branch 3 times, most recently from 0442812 to e014ee1Compare July 11, 2026 20:24

Astro-Han added 18 commits July 12, 2026 04:59

docs(ui): add architecture README for @maka/ui
019cb03

docs(desktop): add architecture READMEs for the desktop app and renderer
7183d49

Astro-Han force-pushed the docs/frontend-architecture-readmes branch from 113e3c7 to 66bcf23Compare July 11, 2026 20:59

Astro-Han merged commit 57b73ef into mainJul 11, 2026
3 checks passed

Astro-Han deleted the docs/frontend-architecture-readmes branch July 11, 2026 21:20

Astro-Han mentioned this pull request Jul 12, 2026
RFC: establish repository and documentation ownership boundaries #767
Closed

Astro-Han mentioned this pull request Jul 11, 2026
fix(runtime): give FormatJson the edit activity kind #726
Merged
5 tasks

Astro-Han force-pushed the docs/frontend-architecture-readmes branch 3 times, most recently from 0442812 to e014ee1Compare July 11, 2026 20:24

Astro-Han added 18 commits July 12, 2026 04:59

docs(ui): add architecture README for @maka/ui
019cb03

docs(desktop): add architecture READMEs for the desktop app and renderer
7183d49

Astro-Han force-pushed the docs/frontend-architecture-readmes branch from 113e3c7 to 66bcf23Compare July 11, 2026 20:59

Astro-Han merged commit 57b73ef into mainJul 11, 2026
3 checks passed

Astro-Han deleted the docs/frontend-architecture-readmes branch July 11, 2026 21:20

Astro-Han mentioned this pull request Jul 12, 2026
RFC: establish repository and documentation ownership boundaries #767
Closed

Astro-Han mentioned this pull request Jul 11, 2026
fix(runtime): give FormatJson the edit activity kind #726
Merged
5 tasks

Astro-Han force-pushed the docs/frontend-architecture-readmes branch 3 times, most recently from 0442812 to e014ee1Compare July 11, 2026 20:24

Astro-Han added 18 commits July 12, 2026 04:59

docs(ui): add architecture README for @maka/ui
019cb03

docs(desktop): add architecture READMEs for the desktop app and renderer
7183d49

Astro-Han force-pushed the docs/frontend-architecture-readmes branch from 113e3c7 to 66bcf23Compare July 11, 2026 20:59

Astro-Han merged commit 57b73ef into mainJul 11, 2026
3 checks passed

Astro-Han deleted the docs/frontend-architecture-readmes branch July 11, 2026 21:20

Astro-Han mentioned this pull request Jul 12, 2026
RFC: establish repository and documentation ownership boundaries #767
Closed

Astro-Han mentioned this pull request Jul 11, 2026
fix(runtime): give FormatJson the edit activity kind #726
Merged
5 tasks

Astro-Han force-pushed the docs/frontend-architecture-readmes branch 3 times, most recently from 0442812 to e014ee1Compare July 11, 2026 20:24

Astro-Han added 18 commits July 12, 2026 04:59

docs(ui): add architecture README for @maka/ui
019cb03

docs(desktop): add architecture READMEs for the desktop app and renderer
7183d49

Astro-Han force-pushed the docs/frontend-architecture-readmes branch from 113e3c7 to 66bcf23Compare July 11, 2026 20:59

Astro-Han merged commit 57b73ef into mainJul 11, 2026
3 checks passed

Astro-Han deleted the docs/frontend-architecture-readmes branch July 11, 2026 21:20

Astro-Han mentioned this pull request Jul 12, 2026
RFC: establish repository and documentation ownership boundaries #767
Closed

Astro-Han mentioned this pull request Jul 11, 2026
fix(runtime): give FormatJson the edit activity kind #726
Merged
5 tasks

Astro-Han force-pushed the docs/frontend-architecture-readmes branch 3 times, most recently from 0442812 to e014ee1Compare July 11, 2026 20:24

Astro-Han added 18 commits July 12, 2026 04:59

docs(ui): add architecture README for @maka/ui
019cb03

docs(desktop): add architecture READMEs for the desktop app and renderer
7183d49

Astro-Han force-pushed the docs/frontend-architecture-readmes branch from 113e3c7 to 66bcf23Compare July 11, 2026 20:59

Astro-Han merged commit 57b73ef into mainJul 11, 2026
3 checks passed

Astro-Han deleted the docs/frontend-architecture-readmes branch July 11, 2026 21:20

Astro-Han mentioned this pull request Jul 12, 2026
RFC: establish repository and documentation ownership boundaries #767
Closed

Astro-Han mentioned this pull request Jul 11, 2026
fix(runtime): give FormatJson the edit activity kind #726
Merged
5 tasks

Astro-Han force-pushed the docs/frontend-architecture-readmes branch 3 times, most recently from 0442812 to e014ee1Compare July 11, 2026 20:24

Astro-Han added 18 commits July 12, 2026 04:59

docs(ui): add architecture README for @maka/ui
019cb03

docs(desktop): add architecture READMEs for the desktop app and renderer
7183d49

Astro-Han force-pushed the docs/frontend-architecture-readmes branch from 113e3c7 to 66bcf23Compare July 11, 2026 20:59

Astro-Han merged commit 57b73ef into mainJul 11, 2026
3 checks passed

Astro-Han deleted the docs/frontend-architecture-readmes branch July 11, 2026 21:20

Astro-Han mentioned this pull request Jul 12, 2026
RFC: establish repository and documentation ownership boundaries #767
Closed

Uh oh!

Conversation

Astro-Han commented Jul 11, 2026

Summary

Why

Scope

Verification

User-facing impact

Reviewer notes

Checklist

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

Astro-Han commented Jul 11, 2026

Summary

Why

Scope

Verification

User-facing impact

Reviewer notes

Checklist

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

Astro-Han commented Jul 11, 2026

Summary

Why

Scope

Verification

User-facing impact

Reviewer notes

Checklist

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

Astro-Han commented Jul 11, 2026

Summary

Why

Scope

Verification

User-facing impact

Reviewer notes

Checklist

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant