# Introduction
## Working with AI
AI is changing the way we design, build, and interact with digital products. Working with AI is where we document how AI can be used effectively, responsibly, and consistently alongside our Design System.
This space brings together the tools, workflows, guidelines, and shared practices that help teams use AI as part of their day-to-day work.
Working with AI is not about AI for its own sake. It is about finding practical ways to augment our workflows while keeping the Design System at the center of how we design and build, in ways that remain compatible with Thales constraints, security requirements, and working environment.
## Security notice
AI tools can support design and development workflows, but they must be used within the constraints of the Thales environment.
Not every AI tool can be used to process our data, assets, or work context. Teams must rely on validated tools and approved environments, and avoid external dependencies that introduce known vulnerabilities or send sensitive data outside authorized boundaries.
This means:
- using validated tools and approved environments for work-related activities
- avoiding external dependencies that introduce known vulnerabilities
- ensuring that sensitive data, source code, design files, and internal project information are not sent outside authorized environments
The workflows documented in Working with AI are designed with these constraints in mind, so teams can explore AI in a way that remains secure and compliant.
## What you'll find here
Working with AI will evolve as we explore new tools and ways of working. For now, it is organized around a few key areas:
### AI-operability
Understand how Quantum is being structured to work effectively with AI, so components, documentation, and patterns are easier for AI tools to interpret, navigate, and use correctly.
→ [Learn about AI-operability](/docs/working-with-ai/overview/ai-operability/)
### LLM-ready docs
Access Quantum documentation through `llms.txt` indexes, task-focused documentation bundles, and Markdown URLs designed for AI tools, agents, and automation.
→ [Learn about LLM-ready docs](/docs/working-with-ai/overview/llm-ready-docs/)
# AI-operability
This page gives an overview of the progress made toward **making Quantum more AI-operable**.
In this context, AI-operable means making the Design System easier for AI assistants, coding agents, and automated workflows to understand, navigate, and apply reliably.
## AI-operability resources at a glance
The tables below summarize a concise set of high-level resources and assets that matter for AI-operability. They are inspired by the kinds of capabilities highlighted in the broader Design System landscape and can be used as a framework to assess Quantum's current maturity and future priorities.
### 1. Distribution & discovery
| Element | Description | Status |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| MCP server | Exposes components, tokens, icons, patterns and docs as agent tools, either local (stdio) or remote (hosted). This is the most common affordance in mature AI-operable design systems. | |
| `llms.txt` | A root index of docs with one-line descriptions generated from the same source as the docs site. | |
| `llms-full.txt` | A full concatenated dump generated from the same source as the docs site. | |
| Sliced `llms-*.txt` variants | Context-budget slices by concern (components, styling, theming, migration) so agents load only what the task needs. | |
| Markdown twins of docs pages | Every docs page is available as `.md` (URL suffix, `Accept: text/markdown` negotiation, or a "Copy for LLM" button). | |
| Agent-optimized markdown | A denoised markdown layer curated specifically for LLM ingestion, with reduced chrome and explicit structure. | |
| Per-section markdown bundles | Combined markdown exports for the complete documentation corpus and its major sections. | |
| Agent discovery layer | `.well-known/` manifests (skills index, api-catalog, MCP server card), `Link` headers and `sitemap.md` for automatic agent discovery. | |
### 2. Agent instructions
| Element | Description | Status |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| Agent skills | An installable `SKILL.md` router with reference files loaded on demand, plus task-oriented skills for building, migrating and auditing. | |
| Editor rules | `.github/copilot-instructions.md`, path-scoped `.github/instructions/*.instructions.md` and `.cursor/rules/*.mdc`, used to guide agents in consumer or contributor environments. | |
| `AGENTS.md` | Root and per-package instruction files for contributor agents, covering conventions, commands and the definition of done. | |
| `DESIGN.md` | A portable design-context manifest covering principles, tokens and key do/don’t rules. It should be treated as a complement, not as the primary agent interface. | |
| AI documentation section | A dedicated documentation section covering setup, supported tools, sample prompts, workflows and usage guidance for AI-assisted work. | |
### 3. Tooling
| Element | Description | Status |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| DS CLI | A deterministic action surface for agents (`setup`, `add`, `info --json`, `lint`, `migrate`) that can also generate or install agent configuration in consumer repos. | |
| Lint rules | Design-system-specific lint rules that help enforce token usage, ban deprecated APIs and catch unsupported overrides, ideally with autofix support. | |
| Codemods | Automated migration scripts between Design System versions, with agent-friendly output and predictable execution. | |
| Registry / examples corpus | Addressable, validated code snippets, patterns and templates that serve as canonical references for generation. | |
| Agent hooks | Pre- and post-edit hooks such as format, lint and typecheck that run automatically in agent sessions. | |
| Design tools bridges | Bridges to design tools such as Figma or Penpot, including assets like Code Connect, design-to-code mappings and token mappings. | |
### 4. Quality
| Element | Description | Status |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| Validation loop | A required validation cycle for agent output, typically based on linting, typechecking, accessibility checks and conformance verification. | |
| Compliance checker | A tool that evaluates an interface or a codebase against Design System rules and assets to assess its compliance with the system. | |
| Guardrails | High-level constraints that prevent unsupported output, such as verify-before-use rules, deprecated API bans, token-only styling and approved design-source allowlists. | |
| AI evaluation suite | Prompt-to-expected-output evaluations run in CI on changes to skills, rules, prompts or MCP assets, with pass-rate thresholds and published results. | |
## Why this matters
As AI tools become part of everyday design and development workflows, a Design System is no longer only consumed by humans.
It is also increasingly consumed by:
- coding assistants working inside IDEs
- agents that generate or modify UI code
- tools that inspect design tokens and component APIs
- workflows that connect design, documentation, and implementation
If Quantum is not structured for these use cases, AI-generated output becomes less reliable. It may use the wrong components, invent patterns that do not exist, or produce code that is inconsistent with the system.
Improving AI-operability helps reduce that gap. The goal is not to let AI replace design and engineering judgement, but to make Quantum easier to use correctly in AI-assisted workflows.
# LLM-ready docs
Quantum exposes LLM-friendly documentation endpoints so AI tools, agents, and automation can discover and consume documentation content more easily in both public and private modes.
These endpoints are designed to help with:
- AI-assisted documentation retrieval
- agent navigation across Quantum docs
- downstream indexing pipelines
- lightweight ingestion of documentation content
## `llms-*.txt`
Use the index to discover available content, the full corpus when context limits permit, or a documentation bundle targeted to the task.
### Discovery and full corpus
| File | Description | Link |
| --------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `llms.txt` | A compact index of public documentation, including canonical and Markdown links. | [`/llms.txt`](/llms.txt) |
| `llms-full.txt` | Complete concatenated documentation and published blog content for tools that need the full corpus in a single request. | [`/llms-full.txt`](/llms-full.txt) |
### Documentation bundles
These bundles contain documentation only, without published blog content. Choose the smallest relevant bundle to reduce context use.
| File | Documentation included | Link |
| ---------------------------------- | --------------------------------- | ------------------------------------------------------------------------ |
| `llms-docs.txt` | All public documentation | [`/llms-docs.txt`](/llms-docs.txt) |
| `llms-docs-welcome.txt` | Welcome and contribution guidance | [`/llms-docs-welcome.txt`](/llms-docs-welcome.txt) |
| `llms-docs-foundations.txt` | Design foundations | [`/llms-docs-foundations.txt`](/llms-docs-foundations.txt) |
| `llms-docs-components.txt` | Component documentation | [`/llms-docs-components.txt`](/llms-docs-components.txt) |
| `llms-docs-extensions.txt` | Extensions | [`/llms-docs-extensions.txt`](/llms-docs-extensions.txt) |
| `llms-docs-patterns-templates.txt` | Patterns and templates | [`/llms-docs-patterns-templates.txt`](/llms-docs-patterns-templates.txt) |
| `llms-docs-working-with-ai.txt` | AI-assisted workflows and tools | [`/llms-docs-working-with-ai.txt`](/llms-docs-working-with-ai.txt) |
## Markdown documentation
Every documentation page is also available in Markdown by adding the `.md` suffix to its URL. For example:
| Example HTML page | Example Markdown URL |
| -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| [`/docs/welcome/introduction`](/docs/welcome/introduction) | [`/docs/welcome/introduction.md`](/docs/welcome/introduction.md) |
| [`/docs/working-with-ai/overview/introduction`](/docs/working-with-ai/overview/introduction) | [`/docs/working-with-ai/overview/introduction.md`](/docs/working-with-ai/overview/introduction.md) |
Use HTML pages for browsing and Markdown URLs for tools that need a simpler representation.