---
language: "en"
title: "Getting Started"
canonical: "https://tasty.style/docs/getting-started"
source: "docs/getting-started.md"
index: true
---

# Getting Started

Build one stateful component first. You will see how Tasty expresses priority as a state map, why overlapping states do not compete, and where shared design-system configuration fits afterward.

This is the right starting point when you are ready to try Tasty in code. If you are still evaluating it, read the [Introduction](/docs/), [Comparison](/docs/comparison), and [Adoption Guide](/docs/adoption).

***

## Prerequisites

* **Node.js** >= 20
* **React** >= 18 (peer dependency)
* **Package manager**: pnpm, npm, or yarn

No Tasty configuration is required for the first component.

***

## Install

```bash
pnpm add @tenphi/tasty
```

***

## Build a button whose states don’t fight

```tsx
import { tasty } from '@tenphi/tasty';

const Button = tasty({
  as: 'button',
  styles: {
    padding: '12px 20px',
    radius: '8px',
    border: '0',
    fill: {
      '': 'royalblue',
      ':hover': 'blue',
      ':active': 'navy',
      disabled: 'lightgray',
    },
    color: {
      '': 'white',
      disabled: 'dimgray',
    },
    cursor: {
      '': 'pointer',
      disabled: 'not-allowed',
    },
  },
});

export default function App() {
  return (
    <>
      <Button>Save changes</Button>
      <Button disabled>Disabled</Button>
    </>
  );
}
```

`tasty()` returns a normal React component. The keys in each state map define priority: later branches win over earlier ones. Because `disabled` is last, a disabled button keeps its disabled styles even while the pointer is over it.

`disabled`, `checked`, and `hidden` are built-in automatic states. Tasty sets `data-disabled`, `data-checked`, and `data-hidden` from the matching native prop, so `disabled` in a state map is the concise form of `[disabled]` (it compiles to `[data-disabled]`).

Tasty compiles that priority into selectors that exclude one another. The hover, active, and disabled background rules cannot all match and ask the CSS cascade to decide the winner.

The example uses ordinary CSS values so it works without setup. A design system will usually replace them with shared tokens, units, and state aliases in the next step. See the [Style DSL](/docs/dsl) for the complete state-map syntax and [Style Properties](/docs/styles) for Tasty’s enhanced CSS properties.

***

## Add your design system’s language

The first component needs no configuration. Use `configure()` once, before your app renders, when your app or design system is ready to share tokens, state aliases, recipes, units, or parser extensions:

```tsx
// src/tasty-config.ts
import { configure } from '@tenphi/tasty';

configure({
  states: {
    '@mobile': '@media(w < 768px)',
    '@dark': '@root(schema=dark)',
  },
});
```

These examples use `data-schema="dark"` as the root-state convention. If your app already uses a different attribute such as `data-theme="dark"`, keep the pattern and swap the attribute name consistently across your config and components.

Import this file at the top of your app entry point so it runs before any component renders:

```tsx
// src/main.tsx
import './tasty-config';
import { createRoot } from 'react-dom/client';
import App from './App';

createRoot(document.getElementById('root')!).render(<App />);
```

### Define shared tokens and units

Color tokens like `#primary` and value tokens like `$sidebar-width` resolve to CSS custom properties (`var(--primary-color)`, `var(--sidebar-width)`). Define their values with `configure({ tokens })`:

```tsx
// src/tasty-config.ts
import { configure } from '@tenphi/tasty';

configure({
  tokens: {
    '#primary': 'oklch(55% 0.25 265)',
    '#surface': '#fff',
    '#text': '#111',
    '$sidebar-width': '280px',
  },
});
```

Tokens support state maps for responsive or theme-aware values:

```tsx
configure({
  tokens: {
    '#primary': {
      '': 'oklch(55% 0.25 265)',
      '@dark': 'oklch(75% 0.2 265)',
    },
  },
});
```

Tokens are injected as `:root` CSS custom properties when the first style is rendered, and every component using `#primary` follows them. You can also use standard CSS color values such as `rgb(...)`, `hsl(...)`, and named colors directly; the built-in `okhsl(...)` and `okhst(...)` functions are the recommended choice when you want authored colors that stay aligned with Tasty's design-system-oriented workflow.

Units work differently: `x`, `r`, `cr`, `bw`, and `ow` compile to plain values when styles are generated (`2x` → `16px` with the default `8px` step), so setting a `$gap` token does not change them. Change the scale with `configure({ units })`:

```tsx
configure({
  units: {
    x: '4px', // spacing step: 2x → 8px
    r: '8px', // radius: 1r → 8px
  },
});
```

When the scale has to change at runtime, for example per theme or density, point the unit at a custom property and define that property as a token. With `units: { x: 'var(--gap)' }` and `tokens: { $gap: '8px' }`, `2x` compiles to `calc(2 * var(--gap))`. See [Built-in Units](/docs/dsl#built-in-units) for the defaults.

> **Note:** `configure({ replaceTokens })` is a separate mechanism — it replaces tokens with literal values at parse time (baked into CSS). Use it for value aliases like `$card-padding: '4x'` that should be resolved during style generation, not for defining color or unit values. See [Configuration — Replace Tokens](/docs/configuration#replace-tokens-parse-time-substitution) for details.

See [Configuration](/docs/configuration) for the full `configure()` API — tokens, replace tokens, recipes, custom units, style handlers, and TypeScript extensions.

***

## ESLint plugin

The ESLint plugin catches invalid style properties, bad token references, malformed state keys, and other mistakes at lint time — before they reach the browser. It checks style objects and JSX style props alike, and runs under both ESLint 9+ and oxlint.

### Install

```bash
pnpm add -D @tenphi/eslint-plugin-tasty
```

### Configure

Add the plugin to your flat config:

```js
// eslint.config.js
import tasty from '@tenphi/eslint-plugin-tasty';

export default [
  // ...your other configs
  tasty.configs.recommended,
];
```

### Tell it about your design system

Without project configuration the plugin checks syntax and property names, but it cannot know which tokens, presets, or recipes exist. Add a `tasty.config.ts` at the project root to enable those checks for the names your `configure()` call defines:

```ts
// tasty.config.ts
export default {
  tokens: ['#primary', '#surface', '#text', '$sidebar-width'],
  states: ['@mobile', '@dark'],
  presets: ['h1', 'h2', 't1', 't2'],
  recipes: ['card'],
  importSources: ['@my-org/ui'], // modules that re-export tasty()
};
```

Every list is optional; leaving one out skips that check. `importSources` matters when your design system re-exports `tasty()` from its own module: the plugin only lints calls whose import it can trace.

### What `recommended` catches

| Category            | Rules                                                                                                  | Examples                                                                 |
| ------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| Property validation | `known-property`, `valid-boolean-property`, `valid-sub-element`                                        | Flags typos like `pading` or invalid boolean usage                       |
| Value validation    | `valid-value`, `valid-color-token`, `valid-custom-unit`                                                | Catches `#nonexistent` tokens, bad unit syntax                           |
| State validation    | `valid-state-key`, `no-nested-state-map`, `require-default-state`                                      | Validates state key syntax, ensures `''` default exists                  |
| Structure           | `valid-styles-structure`, `no-important`, `no-nested-selector`                                         | Prevents `!important`, invalid nesting                                   |
| Static mode         | `static-no-dynamic-values`, `static-valid-selector`                                                    | Enforces build-time constraints in `tastyStatic()`                       |
| Style properties    | `valid-preset`, `valid-recipe`, `valid-transition`, `valid-directional-modifier`, `valid-radius-shape` | Validates preset names, recipe references, transition syntax             |
| Token usage         | `no-raw-color-values`, `consistent-token-usage`, `no-raw-transition-duration`                          | Suggests `#color` tokens over raw colors, units over raw pixel lengths   |
| Preferred syntax    | `prefer-shorthand-property`, `prefer-auto-calc`, `prefer-hide`, `prefer-state-negation`, and others    | Suggests `fill` over `backgroundColor`, `(...)` over `calc(...)`         |
| Component props     | `no-style-prop`, `no-classname-prop`, `no-styles-prop`                                                 | Points escape hatches toward `tokens`, `mods`, and the component's props |
| Dynamic styles      | `no-runtime-styles-mutation`, `no-style-spread`                                                        | Warns on JavaScript values and spreads inside runtime style objects      |

### Strict config

For stricter governance, use `tasty.configs.strict`. It adds existence checks for `$` custom properties and `@` state aliases, and validates state definitions in `configure()` and `tasty.config.ts`:

```js
export default [tasty.configs.strict];
```

See the [plugin README](https://github.com/tenphi/eslint-plugin-tasty) for every rule, the oxlint setup, and the experimental type-aware mode for JSX props.

***

## TypeScript autocomplete

Component props are typed from their definitions without extra setup: `modProps` value lists become unions, `variant` is typed from the variant keys, and sub-elements are typed components. To get autocomplete for your own token, preset, and theme names inside style values, register them with module augmentation:

```ts
// tasty.d.ts
import '@tenphi/tasty';

declare module '@tenphi/tasty' {
  interface TastyNamedColors {
    primary: true;
    surface: true;
    text: true;
  }
  interface TastyPresetNames {
    h1: true;
    t2: true;
  }
}
```

See [Configuration → TypeScript](/docs/configuration#typescript) for every augmentation interface and how component props are typed.

***

## Editor support

**[VS Code Extension](https://github.com/tenphi/tasty-vscode-extension)** — Syntax highlighting for Tasty styles in TypeScript/TSX/JavaScript/JSX: color tokens, custom units, state keys, presets, and style properties inside `tasty()`, `tastyStatic()`, `styles` objects, and style functions. It also adds snippets for components, state maps, and `configure()`. Install the `.vsix` from the [latest GitHub release](https://github.com/tenphi/tasty-vscode-extension/releases/latest); the extension is not published to the marketplace.

**[Glaze](https://github.com/tenphi/glaze)** — Not an editor tool, but the fastest way to fill `configure({ tokens })`: it generates light, dark, and high-contrast palettes from one hue in the OKHST color space, solves WCAG and APCA contrast, and exports them as Tasty tokens with `configure({ tokens: theme.tasty() })`. See [Glaze in the README](/docs/#glaze).

***

## Choosing a rendering mode

`tasty()` is the default for all React apps. All `tasty()` components and style functions are hook-free and work as React Server Components without `'use client'`. Zero-runtime delivery is not tied to one API: both server-only `tasty()` and build-time `tastyStatic()` can ship no Tasty styling runtime to the browser.

| Approach                  | Authoring API                               | CSS is generated                    | Tasty runtime in the browser | Best for                                                         |
| ------------------------- | ------------------------------------------- | ----------------------------------- | ---------------------------- | ---------------------------------------------------------------- |
| **Server-only React**     | `tasty()`; optional `@tenphi/tasty/ssr/*`   | During server or static rendering   | None                         | Astro without islands, server-only RSC, SSG                      |
| **Hydrated React**        | `tasty()` plus `@tenphi/tasty/ssr/*`        | During SSR, then on demand in React | Only in hydrated components  | Interactive React apps, Next.js client components, Astro islands |
| **Build-time extraction** | `tastyStatic()` from `@tenphi/tasty/static` | During the build                    | None in file mode            | Non-React frameworks or extraction before rendering              |

Both `tasty()` and `tastyStatic()` share the same DSL, tokens, units, and state mappings.

* **Server-only `tasty()`** keeps the full feature set (`styleProps`, sub-elements, variants) while generating CSS during server rendering. `tasty()` plus `tastyIntegration({ islands: false })` in Astro is the verified concrete setup and ships no client JavaScript. The same server-only architecture applies to Next.js RSC; verify the generated output for your deployment.
* **Hydrated `tasty()`** uses the SSR integrations to batch and deduplicate server CSS, prevent FOUC, and hydrate the client cache. The browser styling pipeline is available only where React components hydrate. See [Server-Side Rendering](/docs/ssr).
* **Build-time extraction** uses the Babel plugin and additional peer dependencies. Choose `tastyStatic()` when CSS must be generated before rendering or when the consumer is not React. File mode ships no styling runtime; inject mode intentionally includes a tiny CSS injector. See [Build-Time Extraction (`tastyStatic`)](/docs/tasty-static).

***

## Next steps

* **[Docs Hub](/docs/docs-hub)** — Pick the next guide by role, styling approach, or task
* **[Methodology](/docs/methodology)** — The recommended patterns for structuring Tasty components: sub-elements, styleProps, tokens, extension
* **[Style DSL](/docs/dsl)** — State maps, tokens, units, extending semantics, keyframes, @property
* **[React API](/docs/react-api)** — `tasty()` factory, component props, variants, sub-elements, style functions
* **[Building a Design System](/docs/design-system)** — Practical guide to building a DS layer with Tasty: tokens, recipes, primitives, compound components
* **[Adoption Guide](/docs/adoption)** — Roll out Tasty inside an existing design system or platform team
* **[Comparison](/docs/comparison)** — Evaluate Tasty against other styling systems
* **[Configuration](/docs/configuration)** — Full `configure()` API: tokens, recipes, custom units, style handlers, TypeScript extensions
* **[Plugins & Extension Points](/docs/plugins)** — Add your own style properties, units, functions, and component props
* **[Style Properties](/docs/styles)** — Complete reference for all enhanced style properties
* **[Debug Utilities](/docs/debug)** — Inspect generated CSS and debug runtime behavior when styles do not look right

***

## Common issues

* Styles are missing on first render: make sure the file that calls `configure()` is imported before any `tasty()` component renders.
* Token or unit values are not what you expect: check your `configure({ tokens, units })` setup, then inspect the generated CSS variables with [Debug Utilities](/docs/debug).
* Changing a `$gap` or `$radius` token does not change `2x` or `1r`: units compile to plain values from `configure({ units })`. Point a unit at the custom property (`units: { x: 'var(--gap)' }`) if it should follow the token.
* The linter accepts unknown tokens or presets: list them in `tasty.config.ts` so the plugin knows what your design system defines.
* You need zero-runtime delivery: use server-only [`tasty()` with server rendering](/docs/ssr) to keep the full React API, or use [`tastyStatic()` build-time extraction](/docs/tasty-static) when styles must be compiled before rendering.
