Agents

Manifest Query API

Programmatic interface for discovering and composing components from the design library. All functions are exported from @buzzvil/design-library/manifest. Deprecated components are excluded by default — agents are steered to the kit primitive named in supersededBy.

Import

TypeScript

import {
  queryByFunnel,
  queryByIntent,
  queryByTag,
  queryByLayer,
  queryByComplexity,
  queryByFlowRole,
  getManifest,
  getCompositionGraph,
  suggestFlow,
  findPairs,
} from '@buzzvil/design-library/manifest';

QueryOptions — deprecated steering

Every filter function accepts an optional second argument of type QueryOptions. The default behaviour excludes deprecated components (thin wrappers superseded by a kit primitive) so agents are always steered toward the canonical implementation.

QueryOptions

{ includeDeprecated?: boolean }

Default false. Pass true to surface deprecated components — useful for migration tooling or legacy call sites. The queried component itself may be deprecated; that does not suppress the call.

Filter functions

Each function returns ComponentManifest[]. All exclude deprecated components by default.

queryByFunnel(stage, opts?)

All components suitable for a funnel stage.

stage: 'awareness' | 'consideration' | 'conversion'

queryByIntent(intent, opts?)

All components with a given interaction intent.

intent: InteractionIntent — e.g. 'engage' | 'reveal' | 'challenge' | 'reward'

queryByTag(tags, opts?)

All components matching any of the given tags.

tags: string[] — matches ANY tag (case-insensitive)

queryByLayer(layer, opts?)

All components in a given architecture layer.

layer: 'ixd' | 'delivery' | 'experiences'

queryByComplexity(level, opts?)

All components at a given complexity level.

level: 'primitive' | 'composite' | 'complex'

queryByFlowRole(role, opts?)

All components that can play a given role in a flow.

role: 'entry' | 'core' | 'reward' | 'exit' | 'transition'

getManifest(id)

Look up a single component by ID. Returns undefined if not found.

id: string → ComponentManifest | undefined

Examples — filter queries

TypeScript

// All components for an awareness campaign
const awarenessComponents = queryByFunnel('awareness');
// → ComponentManifest[] (deprecated excluded by default)

// Components that deliver a reward payoff
const rewardComponents = queryByIntent('reward');

// Kit-tier primitives only (card chrome, labels, backdrops, progress, etc.)
const kit = queryByLayer('delivery');

// Components that can play the 'entry' role
const entryComponents = queryByFlowRole('entry');

// Find a specific component
const spinWheel = getManifest('SpinWheel');
console.log(spinWheel?.tags);            // ['gamification', 'spin', 'prize']
console.log(spinWheel?.compositionRules); // [{ role: 'core', pairsWith: [...] }]

// Include deprecated wrappers (for migration tooling)
const allAwareness = queryByFunnel('awareness', { includeDeprecated: true });
// deprecated items carry: { deprecated: true, supersededBy: 'Surface' }

Composition helpers

suggestFlow(stage, intent, opts?)

Returns an ordered array [entry?, ...core, companions?, reward?, exit?] for a funnel stage + intent. Core is anchored on the component whose intent matches and has the richest composition graph. Entry/reward/exit come from the core's own flow edges. When flow edges are empty, up to 2 pairsWith companions fill the scaffold. Fully deterministic (stable id sort). Deprecated components are excluded by default.

findPairs(id, role?, opts?)

Returns components that pair well with the given component ID, resolved SYMMETRICALLY. Combines (a) the component's own pairsWith targets and (b) every component that lists this component in ITS pairsWith. The role filter narrows FORWARD edges only; reverse (peer-declared) edges are always included. Output sorted by id.

getCompositionGraph()

Returns the full composition graph as a Map<id, { successors, predecessors, pairs, isolated }>. Flow edges are directed (authored sequence). Pair edges are undirected and resolved symmetrically. Kit primitives (Surface/Pill/Scrim/Progress/Bubble) have no flow edges but rich pair adjacency — getCompositionGraph includes them via pairs, not as isolated nodes.

Examples — composition

TypeScript

// Suggest a flow for an awareness campaign with an 'engage' mechanic
const flow = suggestFlow('awareness', 'engage');
// → [WelcomeScreen, SpinWheel, Burst, CouponCard]
// Each entry is a full ComponentManifest; map to component names:
const componentNames = flow.map((m) => m.id);

// Find what pairs well with SpinWheel (symmetric)
const spinWheelPeers = findPairs('SpinWheel');
// → includes CouponCard, Burst, etc.
// Also returns components that list SpinWheel in THEIR pairsWith,
// even if SpinWheel's own manifest doesn't declare the reverse.

// Role-filtered pairs: only components that can play 'reward' alongside SpinWheel
const rewardPeers = findPairs('SpinWheel', 'reward');

// Full graph — useful for building a visual composition explorer
const graph = getCompositionGraph();
const spinEntry = graph.get('SpinWheel');
// { successors: ['Burst', ...], predecessors: ['WelcomeScreen'], pairs: [...], isolated: false }

// Kit primitives appear in 'pairs', not isolated
const surfaceNode = graph.get('Surface');
// { successors: [], predecessors: [], pairs: ['Pill', 'Scrim', ...], isolated: false }

Deprecated / supersededBy steering

Some components are thin wrappers or presets that were superseded when a kit primitive shipped. Queries exclude them by default so agents always land on the canonical implementation.

TypeScript

// Default: deprecated excluded, agents land on the kit primitive
const labels = queryByTag(['label']);
// → [Pill]   (not the deprecated BrandPill/RewardPill wrappers)

// Migration tooling: surface deprecated components and their replacement
const all = queryByTag(['label'], { includeDeprecated: true });
const deprecated = all.filter((m) => m.deprecated);
deprecated.forEach((m) => {
  console.log(`${m.id} → use ${m.supersededBy ?? '(no replacement listed)'}`);
  // e.g. "BrandPill → use Pill"
});

Type reference

Key types exported from @buzzvil/design-library/manifest. Import them alongside the query functions.

ComponentManifest

id, name, layer, category, description, funnelStages, intent, complexity, tags, compositionRules, flowSuccessors, flowPredecessors, dependencies, deprecated?, supersededBy?

QueryOptions

{ includeDeprecated?: boolean } — default false

FunnelStage

'awareness' | 'consideration' | 'conversion'

InteractionIntent

FlowRole

'entry' | 'core' | 'reward' | 'exit' | 'transition'

ComplexityLevel

'primitive' | 'composite' | 'complex'