# System overview

> Kesko Design System is a set of @kesko/* packages that Kesko product teams install into their apps. Below is a compact map of what each package does and which one to reach for first.

## What you’re working with

A set of `@kesko/*` packages you install into your Kesko product. All public identifiers share the `k-` prefix. Sizes follow a T-shirt scale (`4xs`, `3xs`, `2xs`, `xs`, `sm`, **`md` is default**, `lg`, `xl`, `2xl`, `3xl`). Accessibility and machine-readability come first. The system is still in alpha, so some APIs will change.

## Packages

| Package              | What you get                                                                                                                                                                                                       | Deeper skill        |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- |
| `@kesko/color`       | A contrast-based color palette. 10 families, 12 steps each, plus a dedicated `neutral-dark` palette for dark mode.                                                                                                 | `kesko-colors`      |
| `@kesko/tokens`      | Design tokens for color, typography, spacing, motion, radius, shadow, z-index, opacity, and size. Available as CSS, SCSS, LESS, JavaScript, TypeScript, JSON, iOS Swift, and Android XML.                          | `kesko-tokens`      |
| `@kesko/fonts`       | The SkattaSansUI typeface as `@font-face` declarations plus `.woff2`, `.woff`, and `.ttf` files. 8 variants, with a `system-ui` fallback tuned to match SkattaSansUI’s metrics.                                    | `kesko-fonts`       |
| `@kesko/iconography` | 372 SVG icons on a 24×24 grid, organized by category and tag. Pick a tree-shakeable React component, the `Icon` wrapper, a plain ES module, or the raw `.svg` file.                                                | `kesko-iconography` |
| `@kesko/css`         | A lightweight CSS framework. `kesko.min.css` bundles tokens, the typeface, and `k-`prefixed utility classes. An optional add-on, `components.min.css`, mirrors `@kesko/components` styles for plain-HTML projects. | `kesko-styles`      |
| `@kesko/themes`      | Per-brand CSS overrides on top of `@kesko/tokens`, with auto-generated dark mode. Covers 8 Kesko brands: `kesko`, `k-ruoka`, `k-rauta`, `kespro`, `k-business`, `k-tools`, `k-auto`, and `onninen`.                | `kesko-themes`      |
| `@kesko/components`  | A React component library with paired plain-HTML examples styled by `@kesko/css`. Currently ships `Button`, `Spinner`, `Stack`, and `VisuallyHidden`. Still in early alpha.                                        | `kesko-components`  |

## Picking the right package for a task

- **Looking up a token value or CSS custom property name.** Reach for `@kesko/tokens`.
- **Extending a palette, or asking how dark mode is derived.** Reach for `@kesko/color`.
- **Styling plain HTML or a non-React project.** Start with `@kesko/css`. Add `components.min.css` only if you need `.k-button`, `.k-stack`, and other component classes without React.
- **Building a React app.** Install `@kesko/components` and import `@kesko/css/dist/kesko.min.css`. Do not also load `components.min.css`: `@kesko/components` already ships its component CSS per-component, so the two would duplicate rules.
- **Loading the typeface.** It is normally included through `@kesko/css`. Reach for `@kesko/fonts` standalone only when you do not want the tokens and utilities that `@kesko/css` bundles.
- **Switching brand, or adding a new brand.** Use `@kesko/themes`. Brand definitions live in `@kesko/tokens/themes/`, and the generated CSS ships in `@kesko/themes`.
- **Picking an icon, or labeling one for screen readers.** Reach for `@kesko/iconography`.

## Naming conventions recap

- Everything public uses the `k-` prefix (CSS classes, custom properties, design tokens). Private or internal custom properties use `--_k-*`.
- React components are `PascalCase` nouns (for example, `Button`, `VisuallyHidden`). Their root class is `.k-{name}`.
- Semantic color tokens: `k-color-{role}-{modifier}` (for example, `k-color-text-accent`). Primitive palette: `k-color-{family}-{step}`, with steps from 100 to 1200.
- Sizes always use the short T-shirt form. The `-md` suffix is the default (`k-font-size-md` is the base font size, not an alias to another token).

For the full rules, load `kesko-naming`.

## Where to go next

- Rules for adding or renaming anything: `kesko-naming`.
- Design variables (colors, spacing, typography, motion, and more): `kesko-tokens`.
- Palette theory, contrast steps, and dark-mode derivation: `kesko-colors`.
- Typeface setup: `kesko-fonts`.
- Brand theming: `kesko-themes`.
- Icons: `kesko-iconography`.
- React components and HTML examples with full APIs: `kesko-components`.
- The utility-class CSS framework: `kesko-styles`.