Skip to content
ContractSpec
Start here

Package manual · platform

·Interfaces, presentations and design

lib.design-catalog

Serializable built-in design pack and theme catalog for ContractSpec applications.

platformlibraryv3.0.4stableservernode
@lssm-tech/lib.design-catalog
bun add @lssm-tech/lib.design-catalog
Package source ↗Manifest ↗

Manifest declarations describe the current workspace; they do not verify registry publication or runtime execution.

Package guide

./visual-scenario-spec exposes the complete original validateVisualScenario and validateVisualAuthoring implementations with their supplied presentation and binding context types. The validators preserve default context, diagnostic ordering and paths, React presentation requirements, nested binding resolution, authoring rules, and fail-closed snapshot publishing. They use the canonical scenario model and complete portable Core presentation model, without rendering or collecting evidence. Legacy visual-scenario validator imports remain exact forwards to these same functions.

./themes, its validation leaves, and ./design-packs with its exact subpaths own the complete reusable theme and design-pack families. Original legacy imports forward to these same definitions, nominal registry classes, Editorial defaults, selection policies, safe patch checks, and resolver implementations. Both registry classes extend the shared generic registry in the runtime kernel. The narrow ./visual-scenario-spec leaf owns the complete pure visual case model used by the catalog. ./visual-scenario-registry owns the same nominal scenario registry and ./visual-scenario-platform owns the visual-testing capability and Storybook feature. Legacy imports forward to these exact values; capture runtime remains separate. Existing Catalog consumers use local canonical definitions.

Serializable, versioned design packs for ContractSpec applications.

The package exports 30 certified built-ins, their ThemeSpec values, independent industry/style taxonomy, manifest, registries, deterministic style profiles, and catalog certification. Every built-in declares complete, contrast-safe light and dark semantic palettes, explicit body/heading fonts, web/native support, reduced-motion behavior, and all eight canonical surface recipes. Certification fails closed when a required authored token is absent, and normalized signatures prevent visually duplicate built-ins.

The Editorial design pack retains the stable contractspec.editorial@1.0.0 theme identity while publishing the same complete token groups as every other certified built-in.

contractspec.design.executive-ledger@2.0.0 is the canonical CompanyOS pack. It pairs Newsreader headings with IBM Plex Sans interface copy and IBM Plex Mono evidence, using independently authored parchment/mineral/oxblood and carbon/bone/brass light and dark palettes. Pin version 2.0.0; the former generated 1.0.0 palette is not a compatible substitute.

ts
import {
  BUILT_IN_DESIGN_PACKS,
  DESIGN_PACK_REGISTRY,
  DESIGN_THEME_REGISTRY,
  certifyDesignPack,
} from "@lssm-tech/lib.design-catalog";

const result = certifyDesignPack(
  BUILT_IN_DESIGN_PACKS[0],
  DESIGN_THEME_REGISTRY,
);

Design packs own presentation only. Resolve RoleMorph authorization and bounded personalization before applying a registered design recipe.

Brand packs

LSSM_BRAND_DESIGN_PACKS and LSSM_BRAND_THEMES (registries lssmBrandDesignPackRegistry and lssmBrandDesignThemeRegistry) hold the LSSM atlas, Tellshift and Patio packs (contractspec.design.lssm-atlas, contractspec.design.tellshift, contractspec.design.patio, stability experimental). They are kept apart from the 30 generic built-ins, so the built-in registries, the visual matrix and Storybook counts are unchanged, and contractspec design css does not emit them yet. Their palettes (./lssm-atlas-palette, ./tellshift-palette, ./patio-palette) map each donor custom property onto a token; dark modes are derived by the palette factory.

Since D117-DS-01 each brand pack extends a family base: LSSM atlas over neutral-base, Tellshift over storytelling-base and Patio over ecosystem-base; its entry, theme and pack bytes are unchanged apart from that extends ref. lssmBrandDesignPackRegistry and lssmBrandDesignThemeRegistry also hold the family bases, so resolve() finds each parent.

Family base packs

FAMILY_BASE_DESIGN_PACKS and FAMILY_BASE_THEMES (./family-design-packs, data in ./family-base-catalog) are seven brand-neutral certified base packs, one per product family (career, hiring, mission, creator, storytelling, ecosystem) plus neutral-base, which fits every family. They sit in their own family catalog, so the 30 built-ins, the visual matrix counts and the Storybook hash are unchanged. A brand configures one FamilyBrandPatch (./family-brand-patch, data only) over its family base and presentation.designPack in its composition. selectCompositionDesignPack (./family-design-selection) is pure and deterministic and refuses rather than falls back: an unknown ref, a broken or cyclic chain, a root that is not a family base, a base of another family and a missing theme. Presentation only; it never grants authority.

BRAND_FONT_MANIFESTS (./brand-font-manifests) describes the brand fonts. Web fonts are woff2 from pinned @fontsource packages (@fontsource/inter, and @fontsource/newsreader for Tellshift headings), declared by each host. Social-image rendering uses the committed ttf files in src/fonts/ whose sha256 and license files (beside each font) are pinned and checked byte for byte by the tests. Patio EB Garamond and Cousine are unacquired: their reviewed subset digests are recorded and the pack renders the declared Georgia and monospace fallbacks. validateBrandFontManifest rejects remote URLs, a format that does not match its use, malformed digests, missing licenses and missing fallbacks. verifyBrandFontDigests compares host-computed digests and never reads or fetches files.

Static CSS and visual coverage

The published css/ directory contains one deterministic light/dark artifact per built-in pack plus css/index.css. Import a single pack file or the index.

DESIGN_VISUAL_MATRIX describes the canonical 30 × 8 × 4 screenshot suite, including mobile/desktop web and phone/tablet native-token profiles. Both modes, both platforms, reduced motion, and every registered surface recipe are covered.

Measured surface contrast

measureThemeSurfaceContrast(theme) / findSurfaceContrastFailures(theme) compute WCAG ratios from a theme's actual light and dark colour tokens: 4.5:1 for text pairs (background, card, popover, primary, secondary, muted, accent and state colours, plus primary as text on background and card) and 3:1 for the ring and focusRing indicators. Pack metadata such as componentProfile.accessibility is not a measurement, and a missing or non-hex token fails closed. Every built-in pack is gated by src/surface-contrast.test.ts. Built-in palettes derive readable ink with ensureContrast, which leaves passing colours untouched.

resolveDesignSelection accepts an optional scope (tenantId, userId, appId); a private selection recorded for another scope is ignored with the user_selection_scope_mismatch diagnostic after an account or workspace switch.

Storybook catalog

The opt-in @lssm-tech/lib.design-catalog/storybook export is data-only. It embeds eight VisualScenarioSpec values derived directly from the web entries of DESIGN_VISUAL_MATRIX (30 packs × 8 surfaces × 2 profiles = 480 cases). The host resolves @lssm-tech/lib.design-system/storybook-bindings and @lssm-tech/lib.design-system/storybook-preview; this package does not import React, Storybook, or the Storybook integration at runtime. The repaired matrix uses real design-system surface bindings, complete pack tokens, local fonts, and classified synthetic fixtures; its 480 web cases are approved for governed Chromatic capture.

Run bun run storybook:generate to refresh the committed scenario hash and bun run storybook:check to fail on scenario or case drift.

Generate or verify artifacts with contractspec design css, contractspec design certify, and contractspec design preview. Developer registries can be checked without publishing by passing --module to certify or preview.

Rich-field form fixture

@lssm-tech/lib.design-catalog/forms/rich-fields-showcase exports the existing RichFieldsShowcaseForm singleton for field authoring, renderer checks and surface certification. Its original Zod-backed model is constructed once before the same form identity factory call. The fixture owns no renderer, provider or populated runtime registry; Legacy imports forward to the canonical singleton.

Custom designs from product packs

materializeCustomDesign({ ref, base, patch, owner, catalog? }) applies a validated safe patch to a pinned base. catalog ({ packs, themes }) defaults to the built-in packs; a product can pass its own certified packs (for example COMPANYOS_CUSTOM_DESIGN_BASES from @lssm-tech/bundle.managed-companyos/design) so tenants can start custom designs from them. Unknown bases still throw Custom design base not found.

Relationships

THIS PACKAGElib.design-catalog53 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

4 declarations

Declared capabilities

Lib Design Catalog

Serializable built-in design pack and theme catalog for ContractSpec applications.

Scripts

  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • lint:checknode ../../../../scripts/biome.cjs check .
  • storybook:generatebun scripts/storybook-catalog.mjs
  • storybook:checkbun scripts/storybook-catalog.mjs --check
  • testbun test
  • typechecktsgo --noEmit