Skip to content

README.md

Latest commit

 

History

History
64 lines (45 loc) · 4.86 KB

README.md

File metadata and controls

64 lines (45 loc) · 4.86 KB
Raw

@maka/ui

Shared UI layer for the Maka desktop app. Astryx is the authority for generic components; Maka keeps product-specific composition and state. The package is consumed by apps/desktop's renderer, while the preload bridge imports types only.

The published Astryx API is a fixed dependency boundary. New consumers adapt to its taxonomy instead of recreating retired Maka APIs or styling its internal DOM; existing renderer overrides are acknowledged transitional states documented in apps/desktop/src/renderer/README.md.

Layer map

Four export surfaces, in the order to look:

Surface Role Status
@astryxdesign/core re-exports in src/index.ts Generic design-system components such as Button, TextInput, TextArea, CheckboxInput, RadioList, and Switch. target authority
src/primitives/ Maka-specific compositions that do not duplicate an Astryx component. product-specific
src/ui.tsx Shared product compositions and compatibility-free exports. stable
src/*.tsx / src/*.ts (top-level) Feature components + pure logic (e.g. chat-view.tsx, composer.tsx, sandbox-boundary-prompt.tsx, session-list-panel.tsx, plus pure helpers like materialize.ts and redact.ts). stable
src/components.tsx Re-export barrel for the feature components above (ChatView, Composer, SandboxBoundaryPrompt, …). stable

src/index.ts is the package barrel. It follows an off-barrel convention: some styling tables and per-surface helpers are deliberately not re-exported, so they stay renamable/removable without a public-API break. A symbol earns barrel export when it has a cross-package consumer or an explicit public-API need, not merely a second in-package consumer. Don't add to the barrel speculatively. This README is the source of truth for the barrel promotion rule.

Consuming

import { Badge, Button, ChatView, Composer, PageHeader, useToast } from '@maka/ui';

Sub-path exports (declared in package.json exports): @maka/ui/artifact-preview-registry, @maka/ui/assistant-stream, @maka/ui/icons, and @maka/ui/maka-uri. (@maka/ui/icons re-exports Lucide symbols; model-provider brand logos live in the renderer's settings/provider-*, not here — bot-provider logos are in @maka/ui's bot-brand-logo.)

New renderer CSS owns product layout containers only. It must not target Astryx internal elements, roles, slots, or generated classes to restyle component chrome.

Where new code goes

  • Generic component need → use the closest published Astryx taxonomy and redesign the Maka consumer when the old shape does not fit.
  • Irreducible product control → add the smallest product-named native or Astryx composition; do not create a generic compatibility primitive.
  • New feature component → top-level src/<name>.tsx, kept as a relative import until it has a cross-package consumer or an explicit public-API need; then re-export it from src/components.tsx (index.ts does export * from './components.js', so it lands on the barrel automatically).
  • Don't add a per-surface hand-rolled CSS recipe when Astryx public props can express the need. If they cannot, redesign the consumer; keep a product-owned control only for an irreducible product interaction.
  • Don't re-export a symbol onto the barrel without a cross-package consumer or explicit public-API need; keep it a relative import even with multiple in-package consumers (a cross-package consumer can't use a relative import — previewVariants is re-exported for exactly that reason).

Contracts & guardrails

Product design intent lives in DESIGN.md.

Component behavior, ARIA, keyboard, tone, and token contracts are enforced by source, behavioral tests, focused scripts/check-*.mjs commands, review, and rendered-surface verification. docs/frontend-css-governance.md owns the remaining cross-cutting CSS rules.

Selected primitives and features have stories (stories/) and unit tests (src/__tests__/); coverage is partial, not exhaustive. Build/test entry points are the npm scripts in the root package.json (see the top-level README.md).