OSS-first docs

These docs teach the open system first: contracts, generated surfaces, runtimes, governance, and incremental adoption. Studio shows up as the operating layer on top, not as the source of truth.

Build guide

Implement entity lists, details, and edits with ContractSpec surfaces.

Use one contract-driven DataView for search, filters, result cards or rows, detail opening, and host-owned editing. UseEntityWorkspace for product-shell entity surfaces when you need native-paired workspace chrome, neutral token-backed metrics, evidence blocks, detail panels, and host edit slots. KeepDataViewRenderer for renderer-specific examples and lower-level collection composition.

1. Author the entity DataView

Keep list, grid, table, search, filter, pagination, and personalization defaults in the DataView contract. Link operations throughsource.primary, source.mutations, and action operation refs instead of adding a direct DataView-to-FormSpec field.

1import { defineDataView } from '@lssm-tech/lib.contracts-spec/data-views';
2
3export const CustomerWorkspaceView = defineDataView({
4  meta: {
5    key: 'crm.customers.workspace',
6    version: '1.0.0',
7    title: 'Customers',
8    description: 'Search, review, and update CRM customer records.',
9    domain: 'crm',
10    entity: 'customer',
11    owners: ['@crm'],
12    tags: ['crm', 'customers'],
13    stability: 'stable',
14  },
15  source: {
16    primary: { key: 'crm.customers.list', version: '1.0.0' },
17    mutations: {
18      create: { key: 'crm.customers.create', version: '1.0.0' },
19      update: { key: 'crm.customers.update', version: '1.0.0' },
20    },
21  },
22  view: {
23    kind: 'table',
24    fields: [
25      { key: 'name', label: 'Name', dataPath: 'name', sortable: true },
26      { key: 'owner', label: 'Owner', dataPath: 'ownerRef' },
27      { key: 'arr', label: 'ARR', dataPath: 'arr', format: { type: 'currency', currency: 'EUR' } },
28      { key: 'notes', label: 'Notes', dataPath: 'notes', visibility: { minDataDepth: 'detailed' } },
29    ],
30    columns: [{ field: 'name' }, { field: 'owner' }, { field: 'arr' }],
31    collection: {
32      viewModes: { defaultMode: 'table', allowedModes: ['list', 'grid', 'table'] },
33      toolbar: { search: true, filters: true, viewMode: true, density: true, dataDepth: true },
34      pagination: { pageSize: 25, pageSizeOptions: [10, 25, 50] },
35      personalization: { enabled: true, persist: { viewMode: true, density: true, dataDepth: true, pageSize: true } },
36    },
37  },
38});

2. Render searchable results

Resolve user preferences in the host, then pass ordinary props to the renderer. Treat card clicks, row clicks, and explicit detail actions as the same semantic open-detail event so analytics and keyboard behavior stay coherent.

1import { DataViewRenderer } from '@lssm-tech/lib.design-system';
2import { resolveDataViewPreferences } from '@lssm-tech/lib.personalization/data-view-preferences';
3
4const resolved = resolveDataViewPreferences({ spec: CustomerWorkspaceView, preferences, insights });
5
6<DataViewRenderer
7  spec={CustomerWorkspaceView}
8  items={customers}
9  defaultViewMode={resolved.viewMode}
10  defaultDensity={resolved.density}
11  defaultDataDepth={resolved.dataDepth}
12  pagination={{ page, pageSize: resolved.pageSize ?? 25, total }}
13  onSearchChange={(search) => track({ action: 'search_changed', search })}
14  onFilterChange={(filters) => track({ action: 'filters_changed', filters })}
15  onRowClick={(item) => openDetail(item)}
16/>;

3. Compose detail and edit panels

Use AdaptivePanel for responsive detail/edit panels andRichRef for reference-like fields. Resolve edit UI in this order: feature opToPresentation, feature forms, DataView mutations, DataView action operation refs, then a hostrenderFormSlot fallback with an explicit residual-risk note.

1import { AdaptivePanel } from '@lssm-tech/lib.design-system/components/overlays';
2import { RichRef } from '@lssm-tech/lib.ui-kit-web/rich-ref';
3
4function CustomerDetailPanel({ customer, editForm }: Props) {
5  if (!customer) return null;
6
7  return (
8    <AdaptivePanel
9      open
10      onOpenChange={close}
11      trigger={<button type="button">Open customer</button>}
12      title={customer.name ?? 'Customer detail'}
13      mode="responsive"
14    >
15      <RichRef kindId="object" refId={customer.ownerRef} variant="inline" />
16      {editForm ?? <p>Connect a host FormSpec slot for editing.</p>}
17    </AdaptivePanel>
18  );
19}

4. Apply personalization and RoleMorph

Personalization

Use @lssm-tech/lib.personalization to seed view mode, density, data depth, and page size. Keep the design-system renderer portable by passing resolved props instead of importing personalization inside UI components.

RoleMorph

Resolve hidden fields, hidden or blocked actions, approval states, density, and data-depth adaptation in the host or surface runtime before rendering. Do not leak hidden values in labels, tooltips, or explanations.

Migration checklist

Inventory existing custom panels such as AgentFleetPanel and identify metrics, chips, status badges, actions, evidence blocks, and detail drawers.
Move collection shape into a DataViewSpec before changing UI code.
Replace inert user, customer, file, URL, and object fields with RichRef descriptors.
Use native-paired DataViewRenderer imports for React Native surfaces; keep web-only shell components out of native bundles.
Add tests for empty results, search/filter events, result count, row/card/detail equivalence, redaction, and action visibility.

Agent implementation prompt

1Implement an entity workspace for <entity> using current ContractSpec packages.
2
3Use DataViewSpec as the contract source. Prefer the native-paired EntityWorkspace facade for product-shell entity surfaces; use DataViewRenderer for renderer-specific examples and lower-level collection composition. Make row click, card click, and the explicit detail button call the same open-detail handler. Resolve edit/create through FeatureModuleSpec opToPresentation/forms first, then DataView source mutations or DataViewAction.operation, and use a host renderFormSlot fallback when no contract form is available. Render reference-like fields with RichRef, route panels through AdaptivePanel, seed view mode/density/data depth from @lssm-tech/lib.personalization, and apply RoleMorph/surface-runtime hidden field/action states before rendering. Verify web and native imports separately.

DataViews runtime

Design system

OSS docsbuildStart with OSS. Adopt Studio when you want the operating layer.

Build a contract-driven form

Define schema-backed form data, fields, layout, policy, and submit actions as one reusable ContractSpec surface.

Why ContractSpec

Keep educational and comparison content reachable without letting it define the primary OSS learning path.

Manifesto Contract-first API Spec-driven development

Open system docs