@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/design-core@0.1.0.
• 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

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.

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/design-core@0.1.0 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