@volvo-cars/design-system-agent

Versioned Volvo Cars design system documentation, CSS and icon metadata, and tools for AI agents. The package includes an offline semantic search model and does not fetch model files at runtime.

Installation

Project-local (recommended)

Install the package as an exact development dependency so the project pins its documentation, semantic embeddings, CLI, and bundled skill source together:

# pnpm
pnpm add --save-dev --save-exact @volvo-cars/design-system-agent
pnpm vds install-skill
pnpm vds versions

# Yarn
yarn add --dev --exact @volvo-cars/design-system-agent
yarn vds install-skill
yarn vds versions

# npm
npm install --save-dev --save-exact @volvo-cars/design-system-agent
npm exec -- vds install-skill
npm exec -- vds versions

Commit the package manifest, lockfile, and project-level skill files your team normally tracks. After upgrading the package, run the matching install-skill command again to refresh the installed skill.

Run the pinned CLI through the package manager used by the project. Examples below use pnpm; replace pnpm vds with yarn vds or npm exec -- vds as appropriate.

pnpm vds find "headline with image and buttons"

If application code imports the JavaScript tools, install the exact version as a regular dependency instead:

# pnpm
pnpm add --save-exact @volvo-cars/design-system-agent

# Yarn
yarn add --exact @volvo-cars/design-system-agent

# npm
npm install --save-exact @volvo-cars/design-system-agent

Global CLI

A global CLI and user-level skill are useful as personal defaults across projects that do not pin the package. They can drift from a project's expected documentation, so prefer the project-local installation when one is available.

npm install --global @volvo-cars/design-system-agent
vds install-skill --global
vds --version
vds versions

You can also install the CLI globally with pnpm:

pnpm add --global @volvo-cars/design-system-agent

One-time use

Use npx to try the CLI or bootstrap the bundled skill without keeping the package installed. Prefer a project-local installation for repeated project work.

npx --yes @volvo-cars/design-system-agent find "headline with image and buttons"
npx --yes @volvo-cars/design-system-agent install-skill

Node.js 22.20 or newer is required.

CLI

The CLI prints raw JSON or Markdown without presentation formatting, making its output suitable for scripts and AI agents.

Install the bundled agent skill into the project with the official Skills CLI:

# pnpm
pnpm vds install-skill

# Yarn
yarn vds install-skill

# npm
npm exec -- vds install-skill

Use --global only when you intentionally want a user-level skill rather than a project-versioned skill:

vds install-skill --global

For a one-time global skill bootstrap without installing the CLI first:

npx --yes @volvo-cars/design-system-agent install-skill --global

Every argument after install-skill is forwarded unchanged to skills add. For example, append --agent claude-code codex or --yes --copy. Run pnpm vds install-skill --help, yarn vds install-skill --help, or npm exec -- vds install-skill --help for the official Skills CLI options.

Start with find for design system guidance:

pnpm vds find "headline with image and buttons"
pnpm vds find PasswordInput showPasswordLabel props --content
pnpm vds find dialog close escape --content --content-chars 9000

find joins trailing positional words into one query, so quoted and ordinary unquoted phrases are equivalent. Quote queries when needed to protect shell special characters or whitespace.

Use the returned section and selector to retrieve focused documentation when the search snippets are not enough:

pnpm vds doc components Hero --heading "Media hero"
pnpm vds doc components Button --outline
pnpm vds doc components Button --heading Variants --heading Accessibility

Discover and inspect CSS utilities, icons, and design tokens:

pnpm vds css grid md:p- --max 4
pnpm vds class grid md:p-16
pnpm vds icons car search
pnpm vds icons figma --max 3
pnpm vds tokens --v-color-background-primary --v-space-16

Inspect the bundled design system versions:

pnpm vds versions

| Command | Purpose | | --- | --- | | vds install-skill [options...] | Install the bundled skill through the official Skills CLI | | vds find <query> | Search documentation with hybrid full-text and offline semantic ranking | | vds doc <category> <section> | Retrieve a known section, outline, or heading | | vds docs | List exact documentation categories and section titles | | vds css <query...> | Discover CSS utility names | | vds class <className...> | Inspect exact CSS declarations | | vds icons <query...> | Find valid system and branded icon names | | vds tokens <query...> | Find or verify design tokens | | vds versions | Compare bundled documentation with active local metadata |

CLI reference

Description
  Query versioned Volvo Cars design-system documentation, CSS classes, and tokens for an LLM agent.
  Normal workflow: use `find` for docs, `css` to discover classes, `class` to inspect exact CSS, `icons` before choosing uncertain icon names, and `tokens` only when no utility class fits.
  The CLI auto-detects local @volvo-cars/css and @volvo-cars/react-icons metadata. Use `versions` to compare them with the bundled documentation versions.

Usage
  $ vds <command> [options]

Available Commands
  install-skill    Install the bundled Volvo Cars design system skill using the official skills CLI.
  versions         Show which CSS and React Icons versions the bundled documentation describes and which versions supply searchable metadata.
  docs             List every documentation category and exact section title in one compact JSON object.
  doc              Retrieve content from one known documentation section. Without a mode, returns full content up to 12,000 characters and an outline for larger sections.
  find             Search heading-level documentation chunks with hybrid full-text and bundled offline semantic ranking. This is the primary documentation command.
  class            Return exact CSS declarations for one to ten known class names from the active metadata version.
  css              Search one to ten CSS class queries against the active metadata version.
  icons            Discover valid @volvo-cars/react-icons names for one to ten independent queries before writing Icon, IconButton, or BrandedIcon code.
  tokens           Resolve one to ten independent design-token names or search terms against the active metadata version.

For more info, run any command with the `--help` flag
  $ vds install-skill --help
  $ vds versions --help

Options
  --cwd              Project used to resolve local CSS and React Icons
  --local-css        Require local CSS metadata instead of falling back
  --bundled-css      Ignore local CSS and use bundled metadata
  --local-icons      Require local React Icons metadata
  --bundled-icons    Ignore local React Icons metadata
  -v, --version      Displays current version
  -h, --help         Displays this message

Examples
  $ vds find button
  $ vds find PasswordInput showPasswordLabel props --content
  $ vds css grid md:p-
  $ vds icons car search
  $ vds icons figma --max 3
  $ vds class grid md:p-16
  $ vds tokens --v-color-background-primary --v-space-16
  $ vds install-skill --global

install-skill runs skills add with the bundled skill path and forwards all remaining arguments unchanged. The relevant add section from the bundled [email protected] help is:

Add Options:
  -g, --global           Install skill globally (user-level) instead of project-level
  -a, --agent <agents>   Specify agents to install to (use '*' for all agents)
  -s, --skill <skills>   Specify skill names to install (use '*' for all skills)
  -l, --list             List available skills in the repository without installing
  -y, --yes              Skip confirmation prompts
  --copy                 Copy files instead of symlinking to agent directories
  --metadata <json>      Attach valid JSON to the install telemetry event
  --subagent <names>     Install to Eve subagents (use 'root' for the root agent)
  --all                  Shorthand for --skill '*' --agent '*' -y
  --full-depth           Search all subdirectories even when a root SKILL.md exists

Options:
  --help, -h             Show the official Skills CLI help

Description
  Search heading-level documentation chunks with hybrid full-text and bundled offline semantic ranking. This is the primary documentation command.
  Default output is compact: up to 3 sections, each with up to 2 selectors, sizes, and snippets; no body content or URLs.
  Add `--content` for a specific query to include matched chunk bodies in the same call. The aggregate body budget defaults to 6,000 characters.
  Use `doc --heading` only when search results do not contain enough context.

Usage
  $ vds find <query> [options]

Aliases
  $ vds search-docs
  $ vds search_documentation

Options
  --content          Include matched chunk bodies; default is snippets only
  --content-chars    Aggregate body budget used with --content (500-12000)  (default 6000)
  --cwd              Project used to resolve local CSS and React Icons
  --local-css        Require local CSS metadata instead of falling back
  --bundled-css      Ignore local CSS and use bundled metadata
  --local-icons      Require local React Icons metadata
  --bundled-icons    Ignore local React Icons metadata
  -h, --help         Displays this message

Examples
  $ vds find button
  $ vds find PasswordInput showPasswordLabel props --content
  $ vds find dialog close escape --content --content-chars 9000

Description
  Retrieve content from one known documentation section. Without a mode, returns full content up to 12,000 characters and an outline for larger sections.
  `--outline` returns selectors and character sizes without body content.
  `--heading` returns one selector and its child subsections; repeat it up to five times to fetch related selectors in one call.
  `--full` explicitly requires the complete section and fails above 12,000 characters. Prefer `find --content` before using this command.

Usage
  $ vds doc <category> <section> [options]

Aliases
  $ vds get-doc
  $ vds get_documentation_section

Options
  --outline          Override auto mode: list selectors and sizes only; cannot combine with other modes
  --heading          Override auto mode: return a selector from --outline; repeat up to 5 times; cannot combine with --outline/--full
  --full             Override auto mode: require the full section if <=12000 chars; cannot combine with other modes
  --cwd              Project used to resolve local CSS and React Icons
  --local-css        Require local CSS metadata instead of falling back
  --bundled-css      Ignore local CSS and use bundled metadata
  --local-icons      Require local React Icons metadata
  --bundled-icons    Ignore local React Icons metadata
  -h, --help         Displays this message

Examples
  $ vds doc components Button
  $ vds doc components Button --outline
  $ vds doc components Button --heading Variants --heading Accessibility
  $ vds doc components "Input Fields" --heading "Props > PasswordInput"
  $ vds doc components Button --full

Description
  List every documentation category and exact section title in one compact JSON object.
  Use this only to browse available docs. For a known topic or component, prefer `find <query>`.
  Pass a returned category and section exactly to `doc`.

Usage
  $ vds docs [options]

Aliases
  $ vds list-docs
  $ vds list_documentation_sections

Options
  --cwd              Project used to resolve local CSS and React Icons
  --local-css        Require local CSS metadata instead of falling back
  --bundled-css      Ignore local CSS and use bundled metadata
  --local-icons      Require local React Icons metadata
  --bundled-icons    Ignore local React Icons metadata
  -h, --help         Displays this message

Examples
  $ vds docs

Description
  Search one to ten CSS class queries against the active metadata version.
  Each positional value is a separate query, not one phrase. Use prefixes such as `p-`, `md:p-`, or `hover:text-` for deterministic discovery.
  Returns 4 classes per query by default and identifies queries whose results were truncated. Follow with `class` only if exact CSS is needed.

Usage
  $ vds css <query> [options]

Aliases
  $ vds search-classes
  $ vds search_css_class_names

Options
  -m, --max          Maximum class names per query (1-20; default 4)
  --cwd              Project used to resolve local CSS and React Icons
  --local-css        Require local CSS metadata instead of falling back
  --bundled-css      Ignore local CSS and use bundled metadata
  --local-icons      Require local React Icons metadata
  --bundled-icons    Ignore local React Icons metadata
  -h, --help         Displays this message

Examples
  $ vds css grid md:p-
  $ vds css p- m- gap --max 8
  $ vds css -- -m-

Description
  Return exact CSS declarations for one to ten known class names from the active metadata version.
  Use this after `css` when behavior is unclear. Responsive/state modifiers such as `md:` are validated and preserved.
  Unknown classes return `found: false` instead of a guessed definition.

Usage
  $ vds class <className> [options]

Aliases
  $ vds get-classes
  $ vds get_css_class_definitions

Options
  --cwd              Project used to resolve local CSS and React Icons
  --local-css        Require local CSS metadata instead of falling back
  --bundled-css      Ignore local CSS and use bundled metadata
  --local-icons      Require local React Icons metadata
  --bundled-icons    Ignore local React Icons metadata
  -h, --help         Displays this message

Examples
  $ vds class p-16 md:hidden
  $ vds class -- -m-16

Description
  Discover valid @volvo-cars/react-icons names for one to ten independent queries before writing Icon, IconButton, or BrandedIcon code.
  Each positional value is a separate query. Exact icon names return only the exact match; otherwise results use prefix, contains, and fuzzy matching.
  System results work with Icon and IconButton and support filled variants. Branded results work only with BrandedIcon and do not support filled.
  The response is bounded and never lists the unrestricted icon catalog. Batch all uncertain icon concepts in one command.

Usage
  $ vds icons <query...> [options]

Aliases
  $ vds search-icons
  $ vds search_icons

Options
  -m, --max          Maximum icon names per query (1-20; default 5)  (default 5)
  --cwd              Project used to resolve local CSS and React Icons
  --local-css        Require local CSS metadata instead of falling back
  --bundled-css      Ignore local CSS and use bundled metadata
  --local-icons      Require local React Icons metadata
  --bundled-icons    Ignore local React Icons metadata
  -h, --help         Displays this message

Examples
  $ vds icons car search
  $ vds icons figma --max 3

Description
  Resolve one to ten independent design-token names or search terms against the active metadata version.
  Each positional value is a separate query. An exact CSS token name returns only that token; broad terms use fuzzy search.
  Returns at most 20 results across the whole call. Use tokens only when no suitable utility class exists.

Usage
  $ vds tokens <query> [options]

Aliases
  $ vds search-tokens
  $ vds search_design_tokens

Options
  -m, --max          Maximum fuzzy results per query (1-20; default 10)  (default 10)
  --cwd              Project used to resolve local CSS and React Icons
  --local-css        Require local CSS metadata instead of falling back
  --bundled-css      Ignore local CSS and use bundled metadata
  --local-icons      Require local React Icons metadata
  --bundled-icons    Ignore local React Icons metadata
  -h, --help         Displays this message

Examples
  $ vds tokens --v-color-background-primary --v-space-16
  $ vds tokens background spacing --max 5

Description
  Show which CSS and React Icons versions the bundled documentation describes and which versions supply searchable metadata.
  Version mismatches are allowed: documentation stays bundled while metadata tools use detected local packages.

Usage
  $ vds versions [options]

Options
  --cwd              Project used to resolve local CSS and React Icons
  --local-css        Require local CSS metadata instead of falling back
  --bundled-css      Ignore local CSS and use bundled metadata
  --local-icons      Require local React Icons metadata
  --bundled-icons    Ignore local React Icons metadata
  -h, --help         Displays this message

Examples
  $ vds versions
  $ vds --cwd ../my-app versions
  $ vds --bundled-css versions
  $ vds --bundled-icons versions

Documentation search returns at most three sections with up to two matches per section. It preserves exact identifiers such as TextArea, TextInput, and Switch. Search results contain a followUp object that shows the exact get_documentation_section arguments for retrieving a matched heading.

doc returns full content up to 12,000 characters by default and an outline for larger sections. Use --outline, repeat --heading up to five times, or use --full to require the complete section.

JavaScript Tools

The tools export provides the same bounded operations as the CLI. Tool output is JSON or Markdown text. Documentation search is asynchronous because it runs the bundled semantic model locally.

import { tools } from '@volvo-cars/design-system-agent';

const documentation = JSON.parse(
  await tools.search_documentation.execute({
    query: 'headline with image and buttons',
  }),
);

const hero = tools.get_documentation_section.execute({
  category: 'components',
  section: 'Hero',
  mode: 'heading',
  headings: ['Media hero'],
});

const classes = JSON.parse(
  tools.search_css_class_names.execute({
    queries: ['grid', 'md:p-'],
  }),
);

Available tools:

| Tool | Purpose | | --- | --- | | search_documentation | Primary natural-language documentation search | | get_documentation_section | Retrieve a known section or heading | | list_documentation_sections | List valid categories and section titles | | search_css_class_names | Discover CSS utility names | | get_css_class_definitions | Inspect exact CSS declarations | | search_icons | Find valid React icon names | | search_design_tokens | Find or verify design tokens |

The bundled snapshot and supported package versions are also exported:

import {
  snapshot,
  supportedPackages,
  versionInfo,
} from '@volvo-cars/design-system-agent';

console.log(supportedPackages['@volvo-cars/css']);
console.log(versionInfo);

The complete JSON snapshot is available as @volvo-cars/design-system-agent/snapshot.json.

Project Metadata

Documentation always comes from the versioned bundled snapshot. CSS and icon searches use bundled metadata by default in JavaScript.

The CLI automatically detects @volvo-cars/css and @volvo-cars/react-icons in the current project. A global CLI can target a specific project with --cwd:

vds --cwd ../my-app versions
vds --cwd ../my-app css grid
vds --cwd ../my-app icons car

Use --bundled-css or --bundled-icons for deterministic bundled metadata, or --local-css and --local-icons to require installed project metadata.

JavaScript consumers can opt into local metadata explicitly:

import { createDesignSystemAgent } from '@volvo-cars/design-system-agent';
import { loadLocalCss } from '@volvo-cars/design-system-agent/local-css';
import { loadLocalIcons } from '@volvo-cars/design-system-agent/local-icons';

const agent = createDesignSystemAgent({
  css: await loadLocalCss(),
  icons: await loadLocalIcons(),
});

console.log(agent.versions);

Version mismatches are allowed: documentation remains versioned while metadata tools can reflect the packages installed by the consuming project.