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.
- Node.js >= 20
- React >= 18 (peer dependency)
- Package manager: pnpm, npm, or yarn
No Tasty configuration is required for the first component.
pnpm add @tenphi/tastyimport { 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.
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 />);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.
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.
pnpm add -D @tenphi/eslint-plugin-tastyAdd the plugin to your flat config:
// eslint.config.js
import tasty from '@tenphi/eslint-plugin-tasty';
export default [
// ...your other configs
tasty.configs.recommended,
];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 |
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.
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.
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.
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()plustastyIntegration({ 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).
- 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
- Styles are missing on first render: make sure the file that calls
configure()is imported before anytasty()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
$gapor$radiustoken does not change2xor1r: units compile to plain values fromconfigure({ 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.tsso 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 usetastyStatic()build-time extraction when styles must be compiled before rendering.