Yandex 360 explains how to teach an AI assistant to work with an in-house UI kit

The Yandex 360 frontend team has explained how to teach an AI assistant to work with an in-house UI kit and design system, and why this is impossible without special preparation of the repository.

The "wow" effect and its flip side

First experiments with AI assistants usually impress: an MVP in five minutes, working code on the first attempt, and it seems the future is already here. But when it comes to a real corporate project with internal libraries and its own UI kit, the illusion falls apart. The assistant invents components that already exist in the system, ignores established patterns and breaks design-system conventions.

Yandex 360 ran into this systematically: 90% of the team's frontend developers use AI assistants every day. Incompatibility with internal infrastructure turned out to be the rule, not the exception.

What an AI-ready repository means

Valery Baranov, head of frontend technologies at Yandex 360, explains the root of the problem: public language models were trained on open data. Internal components, corporate libraries and project conventions were not part of it. So context has to be given to the AI explicitly and systematically, rather than through manual hints every time.

The team worked out several principles:

• Structured documentation for every component, written with the model's context window in mind
• Hint files (`AGENTS.md`, `.cursorrules`) describing the architecture and forbidden patterns
• Explicit examples, both correct and incorrect, for every entity
• UI kit metadata that is automatically added to the context on request
• A description of CI/CD and code conventions in a machine-readable format

The design system as a machine-readable artifact

A separate task is teaching the assistant to follow design-system patterns. Internal components are not in the models' training data, so the AI starts to hallucinate: it makes up a nonexistent API or uses outdated patterns.

Yandex 360 added an extra documentation layer. Each component is described not only for the developer but also with the language model in mind: typical mistakes, permitted variants, forbidden combinations. This lets the assistant generate code that passes design review on the first try.

"We made our frontend projects truly AI-ready: we taught assistants to understand the structure of our repositories, work with internal libraries and even follow design-system patterns," said

Valery Baranov, Yandex 360.

An infrastructure view of the problem

Yandex 360 runs a "shared frontend": common technical components, shared CI/CD, and platforms that distribute components between teams. That makes the task especially critical: if one component is described incorrectly, assistants make mistakes in every project that uses it.

That is why the team's approach is not one-off prompt tweaks but systematic work on documentation and repository structure across the whole platform.

What this means

Yandex 360's experience shows that an AI assistant does not become an effective tool without investment in context. Teams that make their repositories and design systems machine-readable will see a real speed gain; the rest will keep spending time fixing hallucinations.