Let the framework wire it

Application code consumes wrappers from @wildo-ai/saas-frontend-lib; the presets package supplies their implementations. Wonder Todos’ registerFrameworkFrontendComponents performs this startup sequence after importing the registration functions:

  registerDefaultIcons();
  registerDefaultPresets();
  registerDefaultAnimations();
  registerBuiltinCommonEnums();
  registerFrameworkLayouts();

  // Tier-1 completeness guard. Throws in dev when a registry-resolved
  // FrontendComponentType is missing a default preset; warns in prod.
  // See compound-component-system.md Section 15 for the Tier-1/Tier-2 model.
  assertRegistryCompleteness();

The function is awaited by the application’s component loader before module-specific registrations. Icons, animations and common enum registrations are separate dependencies of the complete interface; registering components alone is not the whole startup sequence.

Keep interaction contracts when composing a screen

The supplied button maps its public variant to a theme recipe. The actual preset then assembles these states:

  const classes = cn(
    STRUCTURE,
    recipe.base,
    recipe.states.hover,
    recipe.states.active,
    recipe.states.focus,
    recipe.states.disabled,
    recipe.states.invalid,
    recipe.sizes?.[size],
    recipe.motion.transition,
    className,
  )

That is why using the same wrapper carries focus, disabled and invalid appearance into another screen. Its loading state disables the native button and adds aria-busy; the application still controls when loading starts, error feedback and the operation itself. The asChild path composes into another element and does not apply the same loading behavior automatically.

The registry completeness check catches missing injectable slots: it throws in development and warns in production unless strict mode is selected. It does not prove the accessibility, correctness or visual fit of your custom composition. Verify the controls in the real screen, including keyboard use and failure states.

Wonder Todos registers a custom focus view in frontend/src/modules/example-dev/index.ts. This is the actual selected registration; the surrounding module also contributes its view definitions and shell placement.

    {
      componentRef: FOCUS_HUB_SMOKE_COMPONENT_REF,
      loadComponent: async () => {
        const module = await import('./app-level-views/FocusHubSmokeView.js');
        return module.FocusHubSmokeView;
      },
      preset: CorePresetNames.DEFAULT,
      isConfigurable: false,
    },

componentRef must agree with the view definition or wrapper that requests it. loadComponent returns the React implementation. preset selects the registry key; a replacement must meet the props and ref contract expected by the existing wrapper.

The application’s modules-registry.frontend.ts then registers defaults before its module contributions:

    componentLoader: async () => {
      await registerFrameworkFrontendComponents();
      await registerFrontendComponentRegistrations(frontendModuleRegistry.componentRegistrations);
    },

The module belongs in applicationFrontendModules, which feeds buildFrontendModuleRegistry. The resulting componentLoader is handed to application initialization. These asynchronous imports may form separate bundles, but this loader awaits them at startup; they are not automatically deferred until a screen opens.

Replace the edit category without replacing display

An existing resource-reference field uses one slot with separate EDIT and DISPLAY registrations. This illustrative adapter preserves the existing picker’s behavior while adding a local styling hook. It captures the implementation after defaults load, then replaces only the edit key. The public props and forwarded ref remain intact.

import { forwardRef } from 'react';
import {
  ComponentRegistryService,
  type ResourceFieldEditPreset_ResourceReference_DefaultProps as PickerProps,
  type ResourceFieldEdit_ResourceReferenceRef as PickerRef,
} from '@wildo-ai/saas-frontend-lib';
import {
  FrontendComponentType, CorePresetNames, FrontEndComponentResourceFieldCategory,
} from '@wildo-ai/presets-components-models';

export function registerApplicationPicker(): void {
  const slot = FrontendComponentType.RESOURCES_FIELDS_RESOURCE_REFERENCE;
  const preset = CorePresetNames.DEFAULT;
  const category = FrontEndComponentResourceFieldCategory.EDIT;
  const Original = ComponentRegistryService.resolve(slot, preset, category);
  if (!Original) throw new Error('Register framework components before the picker adapter');

  const ApplicationPicker = forwardRef<PickerRef, PickerProps>((props, ref) => (
    <Original
      {...props}
      ref={ref}
      className={['application-reference-picker', props.className].filter(Boolean).join(' ')}
    />
  ));
  ApplicationPicker.displayName = 'ApplicationPicker';

  ComponentRegistryService.register(slot, preset, ApplicationPicker, {
    category,
    isConfigurable: true,
  });
}

Call registerApplicationPicker() once at the end of the application’s component loader, after framework defaults and module registrations. The generated field’s ResourceFieldEdit_ResourceReference wrapper then resolves this exact slot/preset/EDIT key. Its display wrapper continues resolving DISPLAY, which was not changed. The class is an application-owned hook; define its styling in the application’s stylesheet.

Capturing Original before registering avoids resolving the adapter from inside itself. Do not render the public resolving wrapper inside its own replacement: that would recurse. A completely new picker may replace the captured implementation, but must preserve value changes, disabled/error behavior and the forwarded input/button ref. isConfigurable is metadata, not an overwrite lock; the last registration for a key wins.

Choose the replacement boundary deliberately

Direct registry keys also include a field category where applicable. Module contributions merge by componentRef, so two module entries with that same reference do not preserve independent presets merely because their preset names differ.

A missing requested preset does not silently use Default: the resolver shows a development placeholder and renders no component in production. Keep the startup completeness check and exercise the exact preset your screen requests.

The framework’s card specification uses frontendComponentSpecification and names the same LOW_LEVEL_CARD reference used by the runtime. This selected source captures its authoring guidance:

    componentId: 'framework.low-level.card',
    purpose:
      'Group related content with header, title, description, actions, and body regions in a surfaced container.',
    uiRole:
      'Compound card shell: `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardAction`, `CardContent`, `CardFooter`.',
    useWhen:
      'Use for summaries, entity snapshots, dashboard tiles, and form sections that need a clear boundary.',
    avoidWhen:
      'Avoid nesting many interactive cards inside tiny lists without spacing; consider table rows instead.',
    compositionNotes: [
      'Sub-components are separate exports that share the same registry preset.',
    ],

The same specification records CardProps, its preset vocabulary, a compound-card usage example and the implementation/registration symbols. Those connections matter: guidance for an old prop or nonexistent preset would mislead the next author even if the prose sounded useful.

Publish the specification to its consumers

An application-owned specification belongs in its specifications package and must be included in the frontendComponentSpecifications companion export. Wonder Todos already publishes the framework’s specification map there. The companion’s component-specification context factory and labelling context loader read that map to provide component meaning and prop information.

Writing a specification does not register the React implementation. Keep those separate connections aligned when adding a custom slot or preset. Include a useful composition example and explain constraints that a caller must respect; changing only the visual recipe generally belongs in the theme configuration rather than a new component specification.

Wonder Todos starts from DEFAULT_DESIGN_SYSTEM_SOURCE_CONFIG and overrides semantic groups in frontend/src/config/design-system.config.ts. These are actual selected dark-mode values from its colors block:

    dark: {
      ...DEFAULT_DESIGN_SYSTEM_SOURCE_CONFIG.colors.dark,
      background: 'oklch(0.129 0.042 264)',
      foreground: 'oklch(0.968 0.007 247)',
      primary: 'oklch(0.746 0.16 232)',
      'primary-foreground': 'oklch(0.129 0.042 264)',
      secondary: 'oklch(0.279 0.041 260)',
      'secondary-foreground': 'oklch(0.968 0.007 247)',

The selection omits the rest of the dark palette, light palette and enclosing defineDesignSystemConfig call. Background/foreground pairs describe how content reads; primary and its foreground describe an action pair. A change to one should be evaluated with the other.

The application converts the authored source once:

export const frontendResolvedDesignSystemConfiguration =
  createDesignSystemConfigurationFromSourceConfig(designSystemConfig);

That result is passed as designSystemConfiguration in buildFrontendModuleConfigOverrides. UIProvider applies the resolved tokens and appearance; presets retrieve recipes through useUI. A custom component inherits the system when it consumes those tokens and recipes, not merely because it renders somewhere inside the app.

Separate palette, visual treatment and behavior

Use subtle interaction tints for hover and selection rather than treating every accent as a saturated brand color. Test text, focus indicators, disabled controls, charts and third-party content in both modes; token configuration cannot establish their readability by itself.

Wonder Todos’ design-system configuration spreads a theme and then sets application choices. This actual selection shows its shell treatment:

    ...defaultTheme,
    // ...glassTheme,
    // ── Continuous shell chrome ("one canvas", Revolut-style) ──
    // Sidebar / menubar / toolbar / status bar / content zones render as
    // TRANSPARENT regions with no separating borders; the fixed
    // `backgroundLayer` below is the single background that flows under the
    // whole app. Selection/hover structure comes from the alpha
    // `surfaces.sunken-accent` washes above, not from opaque slabs.
    shellAppearance: ShellAppearance.CONTINUOUS,
    // Compact rail shows a small centered label under each icon (labels wrap
    // when long) instead of icon-only + tooltip.
    sidebarCompactLabelMode: SidebarCompactLabelMode.ICON_AND_LABEL,

The comments in this source excerpt describe the application’s current design choice. defaultTheme is imported from @wildo-ai/saas-frontend-lib/companion; optional preset themes are exposed through the deliberate @wildo-ai/presets-components/themes entrypoint.

A theme is a ComponentStyleTheme: its semantic recipes provide base classes, state classes, sizes and motion. For example, the button asks for UIBehavior.INTERACTIVE and the variant corresponding to its public variant prop. A card asks for a surface recipe. Neither screen needs a second implementation just to change these recipes.

Change one recipe and show its consumer

For a calmer primary action, override only the primary recipe’s base and hover treatment. This illustrative theme preserves the other variants, sizes, focus/disabled states, motion and required tokens from cozyTheme.

import { cozyTheme } from '@wildo-ai/presets-components/themes';
import { InteractiveVariant, type ComponentStyleTheme } from '@wildo-ai/presets-components-models';

const primary = cozyTheme.interactive[InteractiveVariant.PRIMARY];
export const applicationTheme: ComponentStyleTheme = {
  ...cozyTheme,
  interactive: {
    ...cozyTheme.interactive,
    [InteractiveVariant.PRIMARY]: {
      ...primary,
      base: 'bg-primary text-primary-foreground rounded-lg font-medium text-sm cursor-pointer shadow-none',
      states: {
        ...primary.states,
        hover: 'hover:bg-primary/90',
      },
    },
  },
};

Select applicationTheme in the design source’s theme, then pass the resolved design system to the application provider. The ordinary public button remains the caller:

<Button variant="default" onClick={saveChanges} disabled={!canSave}>
  {saveLabel}
</Button>

Here saveChanges, canSave and the localized saveLabel belong to the application. The button maps default to InteractiveVariant.PRIMARY, requests its UIBehavior.INTERACTIVE recipe and applies its states and size. That is why changing the recipe reaches this button without changing its action. Other interactive variants keep their inherited recipes.

Preserve dependencies when making an override

Spread the chosen theme before overriding its fields. If the theme owns requiredCustomTokens, preserve those when adding your own; otherwise a recipe can reference a CSS variable that was never emitted. The application’s Tailwind setup must include the package sources and required animation utilities so recipe classes actually exist.

Theme material profiles may add their own runtime behavior and fallback choices. A theme swap is therefore a configuration change to verify on real controls, across both appearances and reduced-motion settings. It does not retheme arbitrary third-party markup or replace application-specific styling automatically.

Wonder Todos assigns the main landmark to its canonical shell in design-system.config.ts:

  surfacePolicies: {
    [SurfaceVariant.SHELL]: {
      a11y: {
        landmarkRole: 'main',
      },
    },
  },

This is a selected configuration block. The shell default does not claim main, allowing an application to choose its owner. A nested shell used only as layout context must avoid claiming a second main region.

Surface merges framework defaults, theme policy, application policy and its call-site policyOverride, in that order. The result is available through useSurfacePolicy; supported values are also emitted as CSS variables and attributes. Current Surface is exported from @wildo-ai/saas-frontend-lib.

Make inheritance an explicit choice

This illustrative composition gives the parent a single-line text policy and lets its child opt into that policy. useSurfacePolicy exposes the resolved value to participating child components; merely nesting arbitrary HTML does not apply truncation to it.

import { Surface } from '@wildo-ai/saas-frontend-lib';
import { SurfaceVariant } from '@wildo-ai/presets-components-models';

<Surface variant={SurfaceVariant.BASE}
  policyOverride={{ content: { textTruncation: 'ellipsis-line' } }}>
  <Surface variant={SurfaceVariant.BASE}
    policyOverride={{ content: { textTruncation: 'inherit' } }}>
    {content}
  </Surface>
</Surface>

content represents application content using the framework’s policy-aware text primitives. With inherit, the child resolves the parent’s value. With reset, it resolves the framework default for that slot instead. Omitting a slot uses the normal variant/theme/application policy chain; nesting alone is not an instruction to copy every parent value.

Give a dialog one behavior owner

When adapting a dialog primitive that already owns focus trapping and scroll lock, use Surface on its content root with asChild and a11yManagedByHost. The existing host must supply a labelled dialog and keyboard/focus behavior; the flag delegates those responsibilities, it does not implement them.

<Surface variant={SurfaceVariant.BASE} asChild a11yManagedByHost
  policyOverride={{ a11y: { landmarkRole: 'none' } }}>
  <DialogContent aria-labelledby={titleId}>
    <DialogTitle id={titleId}>{dialogTitle}</DialogTitle>
    {content}
  </DialogContent>
</Surface>

This is an adapter fragment inside an already configured dialog root. DialogContent and DialogTitle denote that host’s primitives; titleId, the localized title and content belong to the application. Use the host’s public API rather than duplicating its focus handlers. The framework’s standard dialog already composes its own Surface, so do not add a second wrapper around it merely to repeat this pattern.

Connect policy to the CSS consumers

The runtime’s stylesheet contract requires:

@import "tailwindcss";
@import "tw-animate-css";
@plugin "@wildo-ai/saas-frontend-lib/tailwind";

The plugin translates policy variables into layout and presentation rules. Animation utilities supply overlay transitions; duration tokens alone do not create their keyframes.

A policy is not global CSS that transforms arbitrary children. Use the framework’s participating primitives, and adapt third-party containers deliberately. For a local visual tweak use classes; for a change children must understand use policyOverride, without setting the same property through both paths.

Wonder Todos’ frontend/src/config/navigation.config.ts overrides mutation navigation on mobile:

  [ViewportBreakpoint.MOBILE]: {
    transitions: {
      [CoreResourceOperation.CREATE]:  NavigationTransition.PUSH,
      [CoreResourceOperation.UPDATE]:  NavigationTransition.PUSH,
      [CoreResourceOperation.DELETE]:  NavigationTransition.PUSH,
    },
  },

This is a selected block from the application’s NavigationLayout. Its normal primary-zone create, update and delete transitions are overlays; the mobile block selects push. The layout is connected through buildFrontendModuleConfigOverrides, so the navigation resolver consumes it when choosing the destination.

Use the same viewport vocabulary in custom components

The framework defines the named breakpoints centrally:

export enum ViewportBreakpoint {
  MOBILE = '<md',               // Mobile (< 768px)
  VERT_TABLET = '<lg',          // Vertical tablet (768–1023px)
  DESKTOP = '>=lg',             // Desktop (>= 1024px)
}

ComponentsViewportProvider supplies the breakpoint, width, touch capability, reduced-motion preference and platform information; useUI exposes them to participating components. Touch uses the coarse-pointer media query, and reduced motion has its own media query—it is not inferred from screen width.

The navigation policy resolver applies its declared viewport cascade, while the content-area host uses a mobile composition rather than retaining desktop panel splits. A custom component must still consume the relevant signal and implement its intended adaptation. Verify intermediate widths, long translations and keyboard interaction as well as a phone-sized screenshot.

The actual carousel preset requests its component labels and waits for readiness before rendering:

  const { tComponent, isReady } = useI18n({
    component: FrontendComponentType.LOW_LEVEL_CAROUSEL,
  })
  const previousLabel = tComponent(FrontendComponentType.LOW_LEVEL_CAROUSEL, 'previousSlide')

  if (!isReady) return null

The same component puts previousLabel in a sr-only span inside the button. The icon is not the name. This connects language loading, control semantics and the visual preset rather than asking each screen to recreate that connection.

Keep inactive navigation out of the tab order

The navigation content host keeps inactive stack entries mounted and applies inert={!isTop}. Their state survives without leaving hidden controls reachable. Custom hosts must preserve that distinction; opacity alone does not remove keyboard interaction.

Surface activates its shared handlers from the merged policy. This exact runtime excerpt shows why a host-managed dialog does not install a second handler:

const shouldActivateFocusTrap = !a11yManagedByHost
  && (policy.a11y?.focusTrap === 'on-mount' || (modal && policy.a11y?.focusTrap === 'when-modal'));
const shouldActivateScrollContainment = !a11yManagedByHost
  && modal
  && policy.a11y?.scrollContainment === 'lock-body';

useSurfaceFocusTrap(surfaceNodeRef, shouldActivateFocusTrap);
useSurfaceBodyScrollLock(shouldActivateScrollContainment);

Put each responsibility at its owning layer

Wonder Todos opts its canonical shell into a11y.landmarkRole: 'main'. Framework content shells explicitly opt out so nested layout regions do not compete for that role. When a Radix/Vaul host already manages focus or scroll, a11yManagedByHost prevents the surface from installing a second handler.

Use wrappers and their complete label contracts when replacing a component. A custom button that retains only the visual classes can lose its name, keyboard behavior or loading semantics. Test the resulting user journey with keyboard navigation, zoom, assistive technology and both appearances; the shared mechanisms are a foundation, not an automatic conformance claim.

The carousel is a concrete example of the runtime contract:

  const { tComponent, isReady } = useI18n({
    component: FrontendComponentType.LOW_LEVEL_CAROUSEL,
  })
  const previousLabel = tComponent(FrontendComponentType.LOW_LEVEL_CAROUSEL, 'previousSlide')

  if (!isReady) return null

The hook requests the component’s subtree. isReady prevents showing a key while that request is still loading. The returned text is placed in the control’s screen-reader label.

The corresponding current English bundle is:

export const labels = {
  "components": {
    "LOW_LEVEL_CAROUSEL": {
      "previousSlide": "Previous slide",
      "nextSlide": "Next slide"
    }
  }
} as const;

The generated file lives under backend-api/src/engine/i18n/components. The backend serves label trees; it does not invoke language generation during a user request. I18nProvider loads core sections initially, requests other sections or keys as needed, and merges the configured fallback language beneath the active language.

Select the helper that matches the meaning

Use component helpers for component-owned words and resource/field/operation helpers for business interfaces. Register shared enums through registerCommonEnum so recurring values have one named vocabulary; field-specific overrides remain a separate choice.

A custom component must request and render its labels just like a preset. Avoid deriving a user-facing label from an identifier: it loses the authored meaning and cannot replace translation. A missing translation should be corrected in the owning language bundle and generation inputs, not patched by a second string in the screen.

From the application’s Wildo CLI context, with its development companion running, inspect the label plan:

wildo generate labels plan --list

The planner derives units from the connected application registries: resources, components and other supported label owners. This command reads the plan without calling the language model. Confirm the new unit is present before spending a generation run on it.

For example, after confirming the application’s resource:todos unit, the CLI supports:

wildo generate labels --units resource:todos
wildo generate translate --units resource:todos --locales fr

These are command examples using the actual CLI flags, not a claim that generation was run here. The first command uses appPreferences.languages.defaultLanguage; the second targets French. The companion requires its configured model/provider access for generation.

Follow the output into the running application

The companion writes one TypeScript label file per unit and locale under the backend’s owner-scoped i18n tree. The backend’s label loading consumes those files at startup. Translation receives the primary wording and the specification context rather than inferring meaning solely from a key.

Incremental runs skip unchanged work. --force asks to regenerate the selected units; use it deliberately because reviewed wording may change. Generation reduces repetitive authoring, but the application team remains responsible for reviewing the published language.

Wonder Todos declares the application surface in wildo.saas.config.ts with this selected service block:

    app: {
      path: './frontend',
      serviceName: 'wonder-todos-app',
      defaultPort: 4242,
      frontendType: AppFrontendType.SAAS_APP,
      csp: {
        enabled: true,
        reportOnly: true,
      },
    },

This actual example is report-only: it reports violations instead of blocking requests. Its local infrastructure configuration separately adds the required backend origin and PDF worker sources:

    app: {
      extraDirectives: {
        'connect-src': ['http://localhost:4241'],
        // PDF.js parses documents on a Web Worker, and the worker asset is emitted
        // same-origin by the bundler (resolved through `import.meta.url`, never a
        // CDN). Bundlers may instantiate it through a blob shim, so both sources are
        // required — without them a PDF field renders an empty viewer and the only
        // signal is a CSP violation in the console.
        'worker-src': ["'self'", 'blob:'],
      },
    },

The selected block comes from the infrastructure csp map. Website and technical-documentation surfaces have their own service configuration rather than inheriting the app’s permissions accidentally.

Emit the policy for the intended deployment

The owning CLI entrypoint is:

wildo dev sync-csp --env local --service app

This command example names the service key from the declaration above. The resolver combines the surface baseline, authored posture, environment overrides and available declared-provider footprints. It writes src/generated/csp.generated.json and updates the nginx marker regions used for the served header. Browser-surface adapters consume the generated artifact rather than recomputing a separate policy.

Use the actual deployment environment for release preparation. Validate the served header and real asset/API/provider requests before changing report-only to enforcement. A generated file proves what was emitted; the server must still deliver it, and report-only mode never establishes request blocking. Keep generated nginx regions and artifacts under their owning CLI workflow rather than hand-editing them.