@lapismd/design-core

Svelte 5 design-system package for LapisMD applications. It provides native-CSS component families, form primitives, search/filter controls, AI chat presentation, diff views, shell layout, and a workspace framework.

Design Core owns reusable presentation and controller behavior. Consumers own routing, data loading, persistence, domain state, transport, and application policy.

Current package status

• Public package: @lapismd/[email protected].
• Runtime peer: svelte@^5.
• Source package: exports point at tracked .svelte, .ts, and .css source files for modern Svelte/Vite consumers.
• Canonical repository: lapismd/design-core.
• Live catalog: https://lapismd.github.io/design-core/.

Install

This release requires the user-authorized temporary [email protected] pnpm patch. Each installation root must explicitly configure the identical patch and frozen lockfile; Design Core's dependency metadata does not propagate that setup. Follow the packaged patch contract and its checksum manifest before qualifying runtime behavior. The patch retains Link Preview and Slider teardown safety and keyboard focus during repeated FocusScope mounting.

pnpm add @lapismd/design-core svelte

Import the shared stylesheet once at the application boundary:

import "@lapismd/design-core/styles.css";

Then import component families from their public layer:

<script lang="ts">
  import { Button } from "@lapismd/design-core/shadcn/button";
  import { StructuredForm } from "@lapismd/design-core/forms";
  import * as AppShell from "@lapismd/design-core/shell";
</script>

Public layers

| Layer | Import | Use for | | ----------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | Styles and themes | @lapismd/design-core/styles.css, @lapismd/design-core/themes/lapis.css | Theme tokens, base package styles, Lapis theme assets | | shadcn primitives | @lapismd/design-core/shadcn/<family> | Low-level buttons, inputs, dialogs, popovers, menus, tabs, scroll areas, and layout primitives | | Forms | @lapismd/design-core/forms, @lapismd/design-core/forms/core | Structured forms, field renderers, form controls, editors, review/diff affordances | | Filter | @lapismd/design-core/filter | Search bars, power-search tokens, and the filter-query CodeMirror language | | AI | @lapismd/design-core/ai, @lapismd/design-core/ai/chat | Host-controlled chat layout, messages, composer, tool-call, dictation, and status presentation | | AI experimental | @lapismd/design-core/ai/experimental | Lab-derived chat affordances marked experimental | | Diff | @lapismd/design-core/diff | File listings, change stats, file diffs, merge presentation, and headless diff models | | Shell | @lapismd/design-core/shell | Bounded app chrome, sidebars, body regions, responsive shell state, and shell layout persistence adapters | | Workspace | @lapismd/design-core/workspace | Registered views, tabs, splits, sidebars, panels, plugins, commands, settings, and workspace persistence adapters |

Focused component subpaths are also exported for compatibility, especially under forms and workspace. Treat package.json exports as the supported import boundary.

Component coverage

Implemented shadcn families include:

accordion, alert, alert-dialog, badge, breadcrumb, button, button-group, card, checkbox, code, code-block, collapsible, column-canvas, command, command-view, context-menu, dialog, drawer, dropdown-menu, empty, field, hover-card, input, input-group, label, pagination, popover, progress, resizable, scroll-area, select, separator, sheet, sidebar, skeleton, slider, spinner, swipe-item, switch, table, tabs, textarea, toggle, toggle-group, and tooltip.

The higher layers compose these primitives:

• Forms provide structured rendering, YAML/JSON-backed editing, list editors, autocomplete/chip inputs, date/time/reference pickers, code/YAML editors, and patch review surfaces.
• Filter provides reusable search chrome plus parser/language helpers for the filter-query syntax.
• AI provides presentation-only chat parts. It does not own model calls, network transport, conversation storage, or host actions.
• Diff provides file/change/merge UI. Hosts own repository state and file contents.
• Shell provides application chrome and responsive sidebars without owning application navigation.
• Workspace provides the heavier app framework for registered views, layout persistence, commands, panels, and plugins.

Use Shell for application chrome. Use Workspace when the host needs registered views, tab/split layout, plugins, settings, command palette, or full workspace persistence.

Styling contract

Design Core uses native CSS and public custom properties. Consumers should style through tokens and typed props rather than patching internal selectors.

1. Import @lapismd/design-core/styles.css once.
2. Override public --ui-* variables on :root or a shared ancestor.
3. Prefer component props for variants, density, layout, and state.
4. Avoid overriding private DOM structure or internal class names.

Published archives contain prepared browser CSS and font assets. Consumers do not need Tailwind, its Vite plugin, or a source-scanning configuration. Tailwind compilation stays in internal authoring and conversion; generated private CSS variables remain ordinary browser CSS. The existing Mira dependency can still install a Tailwind peer, but Design Core's prepared styles do not use it. Use pnpm package:local when validating the archive boundary rather than importing the unprepared authoring stylesheet.

The source and archive gates reject utility selectors, including compound and nested selectors. Component state cleanup is covered by the slice 2 record. Theme/import restructuring and downstream release remain separate reviewable slices.

Token families:

| Scope | Token examples | Source | | -------------------- | ------------------------------------------------------------------- | ----------------------------------------------------- | | Global theme | --background, --foreground, --primary, --border, --radius | src/theme.css | | shadcn family tokens | --ui-button-*, --ui-input-*, --ui-card-* | colocated family token files | | Forms | --ui-form-* | @lapismd/design-core/forms/form.tokens.css | | AI | --ui-ai-* | @lapismd/design-core/ai/tokens | | Diff | --ui-diff-* | @lapismd/design-core/diff/tokens | | Shell | --ui-shell-* | @lapismd/design-core/shell/shell.tokens.css | | Workspace | --ui-workspace-* | @lapismd/design-core/workspace/workspace.tokens.css |

Component roots stamp stable data-ui-component and data-ui-part attributes for package-owned styling. Consumers may use side-channel attributes for their own selectors, but should not overwrite Design Core identity attributes on package components.

Layout conventions

Source layout follows the public catalog and package layers:

src/
  styles.css, theme.css, storybook.css
  shared/
    shadcn/<family>/
    forms/<family>/
    filter/<family>/
    ai/<component>/
    ai/experimental/<component>/
    diff/<family>/
    shell/app-shell/
    workspace/<family>/

One directory owns one independent component family or one compound family. Multipart components stay together in the owning family folder. Public barrels live at the layer root or family root.

Usage examples

shadcn primitive

<script lang="ts">
  import { Button } from "@lapismd/design-core/shadcn/button";
</script>

<Button variant="default" size="sm">Save</Button>

Shell layout

<script lang="ts">
  import * as AppShell from "@lapismd/design-core/shell";

  const shell = AppShell.createAppShellController({
    layoutId: "app",
  });
</script>

<AppShell.Root controller={shell}>
  <AppShell.Sidebar side="left">
    <AppShell.Sidebar.Header>Navigation</AppShell.Sidebar.Header>
    <AppShell.Sidebar.Body>...</AppShell.Sidebar.Body>
  </AppShell.Sidebar>

  <AppShell.Main>
    <AppShell.Toolbar>Toolbar</AppShell.Toolbar>
    <AppShell.Body>
      <AppShell.Body.Content>Application content</AppShell.Body.Content>
    </AppShell.Body>
  </AppShell.Main>
</AppShell.Root>

Forms

<script lang="ts">
  import { FormField } from "@lapismd/design-core/forms";
  import { Textarea } from "@lapismd/design-core/shadcn/textarea";
</script>

<FormField label="Summary" description="Short text shown in previews">
  <Textarea bind:value={summary} />
</FormField>

Storybook and local documentation

Run the local catalog:

pnpm storybook

Build the static catalog:

pnpm build-storybook

Offline package guidance:

pnpm ui guide
pnpm ui guide styling
pnpm ui components
pnpm ui components button

The canonical specification lives in spec/src. Use it for package behavior, architecture, style rules, and verification evidence:

pnpm spec:search "tokens"
pnpm spec:check

CI and local parity

pnpm checks runs the nonvisual governance, quality, unit, Storybook, pointer, and AI browser lanes through Turbo. Governance, quality, and unit work executes concurrently with half the available processors, capped at four. Resource-heavy Storybook and browser suites run one at a time locally so catalog startup and interaction readiness remain deterministic; set TURBO_CONCURRENCY to a positive number or percentage to override the general task bound.

Local task output is cached under .turbo/. The same tasks use the signed organization cache in CI and fail open to normal execution when it is unavailable. To use the remote cache locally, copy .env.example to the ignored root .env and provide TURBO_TOKEN and TURBO_REMOTE_CACHE_SIGNATURE_KEY. Never commit those credentials.

CI fans the nine nonvisual lanes out in parallel, including separate Workspace, Shell, Shadcn, and AI browser runners. It runs full and production dependency audits after they pass and reports one stable Validate result. Visual comparison remains an explicit, separate command.

Release and validation

Common validation commands:

pnpm spec:first
pnpm spec:check
pnpm check
pnpm test:unit
pnpm build-storybook
pnpm checks:release

Release planning and package artifacts:

pnpm changeset
pnpm release:check
pnpm release:plan --registry https://registry.npmjs.org
pnpm packages:pack

@lapismd/[email protected] was manually bootstrapped from a reviewed tarball. Future releases use Changesets and the repository release workflow.

Further reading

| Resource | Use | | ---------------------------------------------------------------------- | ----------------------------------- | | spec/src/index.md | Canonical Design Core specification | | spec/src/component-inventory.md | Implemented component inventory | | spec/src/styling-and-themes.md | Styling and token contract | | spec/src/packages.md | Public export requirements | | AGENTS.md | Contributor and agent workflow |