Skip to content
Tasty
Color scheme
Contrast
Color scheme
Contrast

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, Comparison, and Adoption Guide.


Prerequisites

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

No Tasty configuration is required for the first component.


Install

pnpm add @tenphi/tasty

Build a button whose states don’t fight

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 for the complete state-map syntax and Style Properties 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:

// 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:

// 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 }):

// 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:

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 }):

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 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 for details.

See 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

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

Configure

Add the plugin to your flat config:

// 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:

// 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.

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:

export default [tasty.configs.strict];

See the plugin README 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:

// 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 for every augmentation interface and how component props are typed.


Editor support

VS Code 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; the extension is not published to the marketplace.

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.


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.
  • 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).

Next steps

  • Docs Hub — Pick the next guide by role, styling approach, or task
  • Methodology — The recommended patterns for structuring Tasty components: sub-elements, styleProps, tokens, extension
  • Style DSL — State maps, tokens, units, extending semantics, keyframes, @property
  • React API — tasty() factory, component props, variants, sub-elements, style functions
  • Building a Design System — Practical guide to building a DS layer with Tasty: tokens, recipes, primitives, compound components
  • Adoption Guide — Roll out Tasty inside an existing design system or platform team
  • Comparison — Evaluate Tasty against other styling systems
  • Configuration — Full configure() API: tokens, recipes, custom units, style handlers, TypeScript extensions
  • Plugins & Extension Points — Add your own style properties, units, functions, and component props
  • Style Properties — Complete reference for all enhanced style properties
  • Debug Utilities — 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.
  • 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 to keep the full React API, or use tastyStatic() build-time extraction when styles must be compiled before rendering.