# CSS framework

> Kesko CSS framework ships the full set of the CSS custom properties, Skatta Sans UI typeface, and Tailwind-style utility classes, with optional component classes as an add-on.

## Installation

To install the CSS framework as a dependency in your project, run:

```sh [npm]
npm install @kesko/css
```

```sh [pnpm]
pnpm add @kesko/css
```

```sh [yarn]
yarn add @kesko/css
```

```sh [bun]
bun add @kesko/css
```

> Warning: Kesko CSS Framework is in active development and not yet ready for production use. APIs documented may change without notice.

---

## Usage

Import the base stylesheet into your project:

```css
@import "@kesko/css/dist/kesko.min.css";
```

This gives you:

1. All `--k-*` custom properties on `:root`
2. `@font-face` declarations for SkattaSansUI (woff2 + woff)
3. Utility classes for colors, typography, spacing, borders, radius, and shadows

### Component classes (optional)

The component classes that mirror `@kesko/components` ship as a separate stylesheet. Load it when you need those components in plain HTML:

```css
@import "@kesko/css/dist/kesko.min.css";
@import "@kesko/css/dist/components.min.css";
```

React consumers do not need this import. `@kesko/components` pulls in the matching CSS per component automatically.

### Applying a brand theme

To apply a brand theme on top, add a theme override from `@kesko/themes`:

```css
@import "@kesko/css/dist/kesko.min.css";
@import "@kesko/themes/dist/k-rauta.css";
```

Because all utility classes reference design token custom properties via `var()`, they automatically adapt when a theme overrides those properties. There is no need for dark mode utility prefixes; swapping a theme file handles it transparently.

---

## Utility classes

Utility class names follow Tailwind CSS conventions, prefixed with `k-`. All directional utilities use CSS logical properties for RTL support.

### Text colors

Set `color` from semantic text tokens.

```html
<p class="k-text">Default text</p>
<p class="k-text-weak">Secondary text</p>
<p class="k-text-accent">Accent text</p>
```

### Background colors

Set `background-color` from semantic background, status, fill, and surface tokens.

```html
<div class="k-bg">Default background</div>
<div class="k-bg-muted">Muted surface</div>
<div class="k-bg-accent">Accent surface</div>
```

### Borders

The base `.k-border` class applies a solid border using `--k-size-border` width and `--k-color-border` color. Directional variants use CSS logical properties. Color variants change only the `border-color`.

```html
<div class="k-border">All sides</div>
<div class="k-border-t">Top only</div>
<div class="k-border k-border-active">Active border color</div>
```

### Font sizes

Set `font-size` from font size tokens. Uses the `text-` prefix following Tailwind convention.

```html
<p class="k-text-sm">Small text</p>
<p class="k-text-lg">Large text</p>
<h1 class="k-text-3xl">Heading</h1>
```

### Font weights

```html
<span class="k-font-normal">Normal</span>
<span class="k-font-bold">Bold</span>
<span class="k-font-black">Black</span>
```

### Font families

```html
<p class="k-font-sans">Sans-serif text</p>
<code class="k-font-code">Monospace text</code>
```

### Line heights

```html
<p class="k-leading-sm">Tight leading</p>
<p class="k-leading-md">Comfortable leading</p>
```

### Padding

Set `padding` from space tokens. Directional variants use CSS logical properties.

```html
<div class="k-p-md">16px padding on all sides</div>
<div class="k-px-lg k-py-sm">24px inline, 12px block</div>
<div class="k-pt-xl">32px padding at block-start</div>
```

Available suffixes: `k-p`, `k-px`, `k-py`, `k-ps`, `k-pe`, `k-pt`, `k-pb`. Available sizes: `4xs`, `3xs`, `2xs`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`.

### Margin

Same directional pattern as padding (`k-m`, `k-mx`, `k-my`, `k-ms`, `k-me`, `k-mt`, `k-mb`), plus `auto` helpers for centering.

```html
<div class="k-m-md">16px margin on all sides</div>
<div class="k-mx-auto" style="width: 20rem">Centered block</div>
```

### Gap

Set `gap` from space tokens, used with flexbox or grid layouts.

```html
<div class="k-gap-md" style="display: flex">
  <div>A</div>
  <div>B</div>
  <div>C</div>
</div>
```

### Border radius

Set `border-radius` from radius scale tokens. `k-rounded` with no size suffix maps to `md` (the system default).

```html
<div class="k-rounded">Default radius (md)</div>
<div class="k-rounded-lg">Large radius</div>
<div class="k-rounded-pill">Pill shape</div>
```

### Box shadows

```html
<div class="k-shadow">Subtle shadow</div>
<div class="k-shadow-float">Floating card</div>
<div class="k-shadow-popover">Popover shadow</div>
```

---

## Component classes

For every component in `@kesko/components`, the framework also ships a matching set of CSS classes, so non-React consumers can apply the same look and feel with plain HTML. Use these for static markup or server-rendered views; for interactive behavior (loading states, keyboard handling, ARIA wiring), reach for [`@kesko/components`](/components/) instead.

### Button

Base class `.k-button`. Stack a variant and size modifier on top.

- Variants: `.k-button-primary`, `.k-button-secondary`, `.k-button-plain`, `.k-button-text`, `.k-button-inverted`
- Sizes: `.k-button-sm`, `.k-button-lg` (default is `md`)
- Modifiers: `.k-button-expand`, `.k-button-transparent`, `.k-button-icon-only`

```html
<button class="k-button k-button-primary">Primary</button>
<button class="k-button k-button-secondary k-button-lg">Large secondary</button>
<button class="k-button k-button-text">Text</button>
<button class="k-button" disabled>Disabled</button>
```

Each button exposes a public theming API via `--k-button-*` custom properties (`-bg`, `-text`, `-border`, `-radius`, and matching `-hover` / `-active` variants). Set them on `:root` or any scoped selector to override defaults for a single instance, a section, or the whole app.

### Spinner

`.k-spinner` wraps four `<span>` children that animate as bouncing dots.

Sizes: `.k-spinner-sm`, `.k-spinner-lg`, `.k-spinner-xl`, `.k-spinner-2xl`. The default size inherits from the current font size, which makes the spinner compose cleanly inside buttons and other text contexts.

```html
<span class="k-spinner" role="status" aria-label="Loading">
  <span></span>
  <span></span>
  <span></span>
  <span></span>
</span>
```

Theming: `--k-spinner-color`, `--k-spinner-size`.

### Stack

`.k-stack` is a flex layout primitive with a `md` gap by default.

- Direction: `.k-stack-row`
- Wrap: `.k-stack-wrap`
- Alignment: `.k-stack-align-center`, `.k-stack-align-end`, `.k-stack-align-stretch`
- Gap: `.k-stack-gap-3xs` through `.k-stack-gap-3xl` (omit for the default `md`)

```html
<div class="k-stack k-stack-row k-stack-gap-sm k-stack-align-center">
  <button class="k-button">A</button>
  <button class="k-button">B</button>
</div>
```

### Visually hidden

`.k-visually-hidden` removes an element visually while keeping it available to assistive technologies. Used for screen-reader-only labels.

```html
<button class="k-button">
  <svg aria-hidden="true">…</svg>
  <span class="k-visually-hidden">Close dialog</span>
</button>
```

---

## Example

Combining utilities and component classes to build a card:

```html
<div class="k-bg k-p-lg k-rounded-lg k-shadow">
  <h2 class="k-text k-text-2xl k-font-bold k-mb-sm">Card title</h2>
  <p class="k-text-weak k-text-sm k-leading-md k-mb-md">Supporting text with muted color and compact size.</p>
  <button class="k-button k-button-primary">Action</button>
</div>
```