# AI features

> Good design systems make the next thing easier to build. Good AI tools should do the same, so Kesko Design System is built for both people and the AI tools they work with.

That means every page is readable both ways. [Hand any page](#llmstxt) to Claude, ChatGPT, or Copilot in one click, or install our [agent skills](#agent-skills) so your AI tools pick up the Kesko Design System conventions automatically.

## LLMs.txt

To streamline development with AI, Kesko Design System publishes its documentation as machine-readable text files that AI assistants and LLMs can consume directly:

| URL                                                    | Description                                                |
| ------------------------------------------------------ | ---------------------------------------------------------- |
| [`/llms.txt`](https://kesko.design/llms.txt)           | Page index with descriptions for every documentation page. |
| [`/llms-full.txt`](https://kesko.design/llms-full.txt) | Full documentation content in a single file.               |
| `/{any-page}.md`                                       | Any docs page as Markdown. Append `.md` to the URL.        |

These files are generated automatically at build time and always reflect the latest published docs. Use them when you need to give an LLM more context on Kesko Design System without installing any packages.

## Usage with AI assistants

AI-powered coding tools can interpret these files to deliver tailored suggestions, code snippets, and answers grounded in Kesko Design System’s actual APIs. There are three common ways to bring the content into a chat:

- **Upload the file.** Most assistants accept plain-text file uploads. Grab `llms-full.txt` and attach it.
- **Copy and paste.** Open any page’s `.md` URL and paste the content into the assistant's input area.
- **Point to the URL.** Tools that can fetch URLs (for example Claude, ChatGPT, or Cursor) can read [https://kesko.design/llms-full.txt](https://kesko.design/llms-full.txt) directly.

Every page with a visible copy menu next to its heading makes the hand-off one click. Pick “Open in Claude” or “Open in ChatGPT” and the assistant opens with a pre-filled prompt pointing at that page’s Markdown.

### Ask high-level questions

With the context loaded, broad questions work well:

- _“What components does Kesko Design System offer for form input?"_
- _“Which semantic color tokens should I use for an error message?"_
- _“How does Kesko Design System handle dark mode?"_

### Generate code examples

For quick snippets, try prompts like:

- _“Show a Kesko Design System `<Button>` that opens an external link.”_
- _“Import the `arrow-down` icon as a tree-shakeable React component.”_
- _“Give me the CSS for a card using Kesko Design System’s CSS Framework.”_

Because the reference includes prop tables, paired HTML and React examples, and real token values, responses match Kesko Design System’s API rather than being guessed.

### Troubleshoot and explore

If something isn’t working, share your code and ask:

- _“Why isn’t my `<Button loading>` spinner showing?”_
- _“What’s the valid size range for `k-font-size`?”_
- _“Is there a Kesko icon that matches 'checkmark'?”_

Advanced features can also be explored:

- _“What brands does `@kesko/themes` ship, and how do their accent colors differ?”_
- _“Show me every token that changes between K-Rauta and Kespro in dark mode.”_
- _“Which icons live in the `navigation` category?”_

## Agentic IDE setup

If you use an agentic IDE, a root-level instructions file gives your assistant permanent context about Kesko Design System’s conventions and how you want it to collaborate with you. Drop a file like this into the root of your host project:

```md
# Design system

When working with @kesko/\* packages, follow the conventions documented at https://kesko.design/llms-full.txt — in particular the `k-` prefix, the T-shirt size scale, and the public vs private CSS custom property split (`--k-` vs `--_k-`).

- **Package maturity** — `@kesko/iconography` and `@kesko/fonts` are stable (v1.x) and ready for production. `@kesko/tokens`, `@kesko/color`, `@kesko/themes`, `@kesko/css`, and `@kesko/components` are still pre-1.0 (alpha or beta) and their APIs can change. Verify any component prop, token name, or import path against https://kesko.design/llms-full.txt before relying on it.
- **Custom styles** — When writing styles beyond the utility classes, always use Kesko Design System's CSS custom properties if possible (`var(--k-color-…)`, `var(--k-font-size-…)`). Never hard-code raw color, font, radius, shadow, or z-index values.

# Working style

- **Work asynchronously** — Run file creation, updates, backups, and research in the background as much as possible. The user often fires off multiple ideas, TODOs, or topics in quick succession. Don't block them waiting for writes and backups to finish.
- **Confirm briefly, keep moving** — Acknowledge what you've captured with a short summary, then be ready for the next input. Don't make the user wait for all the cross-linking and index updates before they can talk again.
- **Batch background work** — When the user gives multiple things at once, process them in parallel using background tasks.
- **Voice your concerns** — User should not have to ask you for your opinion explicitly. Always evaluate what the user is asking you to do, and voice your concerns before proceeding if you don't think it's a good idea. If possible, propose a better solution, but you can voice concerns even without one.
- **Always evaluate** — The above applies even to direct requests. Still evaluate whether your original approach was better. The user may be missing important context. If there was a solid reason why you suggested a certain approach (e.g. avoiding code duplication), push back with reasoning instead of silently complying.
```

The `Design system` pointer tells your AI assistant where to find the Kesko Design System conventions. The `Working style` section is optional but captures the collaboration rules our team uses internally. These can save a lot of re-explanation day-to-day.

Different tools look for the file in different places:

- **Claude Code:** Save as `CLAUDE.md` at the root of your project.
- **OpenAI Codex:** Save as `AGENTS.md` at the root of your project.
- **Cursor:** Save as `.cursorrules` at the root of your project.
- **Cline:** Save as `.clinerules` at the root of your project.
- **Roo Code:** Save as `.roorules` at the root of your project.
- **GitHub Copilot:** Save as `.github/copilot-instructions.md`.
- **Windsurf:** Save as `.windsurfrules` at the root of your project.

## Agent skills

We also provide [agent skills](https://github.com/cloudflare/agent-skills-discovery-rfc) that complement the hosted reference files. Once installed, your AI coding agent automatically picks up Kesko Design System’s authoring patterns on naming, tokens, themes, components, iconography, and styles.

### Install

```sh
npx skills add https://kesko.design
```

The CLI fetches the skills index and lets you choose which skills to install. Skills are then written into your AI agent’s configuration and loaded automatically when needed:

### Available skills

| Skill               | Description                                                                                                                             |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `kesko-overview`    | Includes a compact map of the Kesko Design System and what each package ships and how they fit together.                                |
| `kesko-naming`      | Naming rules for Kesko Design System, covering the k- prefix, T-shirt size scale, tokens, CSS classes, and component props.             |
| `kesko-colors`      | Kesko Design System’s contrast-based color palette with 9 families and 12 steps each, plus a neutral-dark palette for dark mode.        |
| `kesko-fonts`       | Guidelines for using Kesko Design System’s font package that ships the Skatta Sans UI typeface as ready-to-use @font-face declarations. |
| `kesko-tokens`      | Tech-agnostic design variables for colors, typography, and other UI properties, compiled to multiple platform formats.                  |
| `kesko-themes`      | Per-brand CSS overrides for Kesko Design System, with automatic dark mode generation.                                                   |
| `kesko-components`  | Guidelines for Kesko Design System’s component library that ships React and plain HTML components.                                      |
| `kesko-iconography` | Kesko's unified icon library with ~400 vector icons, available as React components, ES modules, and raw SVG files.                      |
| `kesko-styles`      | Lightweight CSS framework bundling design tokens, webfonts, and utility classes, with an optional component classes stylesheet.         |

The raw discovery manifest is served at [/.well-known/agent-skills/index.json](/.well-known/agent-skills/index.json).