stillwind 0.0.0 → 0.1.0-rc.0

package/docs/guides/migrating-from-css.md

@@ -0,0 +1,126 @@
+---
+title: "Migrating from CSS"
+description: "Move styles from plain CSS, CSS Modules, preprocessors, or CSS-in-JS into style() calls and theme tokens."
+---
+
+# Migrating from CSS
+
+You want to move a project that styles elements with plain CSS, CSS Modules,
+Sass, Less, or CSS-in-JS to Stillwind. Unlike a migration from Tailwind CSS,
+you translate declarations into utilities. Check the pages in the browser after
+each step, because the translation can change how elements look.
+
+## Set up Stillwind next to the existing CSS
+
+Install Stillwind and register the build integration as described in
+[Getting started](../index.md). Your existing stylesheets keep working while you
+migrate.
+
+`@import "stillwind"` includes the preflight reset, which changes the default
+styles of elements such as headings and lists. To migrate in steps, leave out
+the reset until the old styles are gone:
+
+```css
+@layer properties, theme, base, components, utilities;
+
+@import "stillwind/theme.css" layer(theme);
+@import "stillwind/utilities.css" layer(utilities);
+@import "stillwind/builtins.css";
+@import "stillwind/templates.css";
+```
+
+Stillwind's CSS is in cascade layers. A declaration outside a layer wins over a
+declaration in a layer, whatever their specificity. While an old rule matches an
+element, it overrides the utilities on that element. Remove the old rule when
+you move its declarations.
+
+## Move values into the theme
+
+Collect the colors, spacing, font sizes, radii, and breakpoints that the old
+CSS repeats, such as Sass variables or custom properties in `:root`. Define them
+as `@theme` tokens by role:
+
+```css
+@theme {
+  --color-surface: oklch(0.98 0 0);
+  --color-accent: oklch(0.6 0.2 250);
+  --breakpoint-tablet: 48rem;
+}
+```
+
+Each token adds utilities, such as `bg-surface` and `tablet:`. Merge values that
+mean the same thing. Keep values separate when they are equal by chance.
+[Design systems](design-systems.md) describes how to name tokens.
+
+## Move rules into style()
+
+Translate the declarations of each rule into utilities, and apply them with
+`style()` on the element:
+
+```css title="Button.module.css"
+.button {
+  padding: 0.5rem 1rem;
+  border-radius: 0.375rem;
+  background: var(--accent);
+}
+
+.button:hover {
+  opacity: 0.9;
+}
+
+.button[disabled] {
+  cursor: wait;
+}
+```
+
+```tsx
+import { style } from "stillwind/react";
+
+export function Button({ loading }: { loading: boolean }) {
+  return (
+    <button
+      disabled={loading}
+      {...style("rounded-md bg-accent px-4 py-2 hover:opacity-90 disabled:cursor-wait")}
+    >
+      Save
+    </button>
+  );
+}
+```
+
+Translate selectors into variants:
+
+| Old CSS                                | Stillwind                                                              |
+| -------------------------------------- | ---------------------------------------------------------------------- |
+| `:hover`, `:focus-visible`, `:checked` | `hover:`, `focus-visible:`, `checked:`                                 |
+| `@media (min-width: 768px)`            | A breakpoint variant, such as `md:`                                    |
+| `[aria-expanded="true"]`, `[data-x]`   | `aria-expanded:`, `data-[x]:`                                          |
+| `.parent:hover .child`                 | A ref, see [Element relationships](element-relationships.md) |
+| A toggled modifier class               | An attribute and its variant                                           |
+| A value set from JavaScript            | A custom property in `style()`                                         |
+
+A declaration without a matching utility can use an arbitrary property, such as
+`[content-visibility:auto]`. When several elements need it, define a custom
+utility instead.
+
+## Replace global rules
+
+- Keep resets and base element styles until you enable the preflight reset.
+  Then remove the rules that it replaces.
+- Move `@keyframes` next to the component that uses them with
+  [style.keyframes()](../macros/keyframes.md).
+- Move styles for HTML that you do not control, such as rendered Markdown, into
+  a custom utility. See [Recommended practices](recommended-practices.md#avoid-separate-css).
+
+## Replace CSS-in-JS
+
+Move static styles from `styled()` components or `css` props into `style()`
+calls. Express props that change styles with attributes and variants, as in
+[Reusable styles](reusable-styles.md). For a continuous value, set a
+custom property in `style()`.
+
+## Check the migrated code
+
+Run the [CLI checks](lint-adoption.md) over the migrated files, and
+compare the pages with the old version in the browser. After you remove the last
+old stylesheet, switch to `@import "stillwind"` and check the pages again.

package/docs/guides/migrating-from-tailwind.md

@@ -0,0 +1,179 @@
+---
+title: "Migrating from Tailwind CSS"
+description: "Move a Tailwind CSS v4 project to Stillwind, from the stylesheet and build to components and configuration."
+---
+
+# Migrating from Tailwind CSS
+
+You want to move an existing Tailwind CSS v4 project to Stillwind. Your utilities,
+variants, theme, and plugins keep working. What changes is where you write them:
+in `style()` calls instead of `className` strings.
+[Tailwind CSS compatibility](tailwind-compatibility.md) lists the tested
+plugins and the differences.
+
+Tailwind scans your files for anything that looks like a class name. Stillwind
+generates CSS only for the utilities in `style()` calls. A class in a plain
+`className` string, or in HTML from another source, gets no CSS after the
+migration. Move every utility that you want to keep into `style()`.
+
+## Replace the stylesheet and the build plugin
+
+In your stylesheet, replace `@import "tailwindcss"` with `@import "stillwind"`:
+
+```css
+@import "stillwind";
+
+@theme {
+  --color-brand: oklch(0.6 0.2 250);
+}
+```
+
+Keep your `@theme`, `@utility`, `@custom-variant`, `@variant`, `@apply`, and
+`@plugin` rules.
+
+Replace the Tailwind build plugin, such as `@tailwindcss/vite`, with the
+Stillwind integration. Then create `stillwind.config.ts`, as described in
+[Getting started](../index.md#configure-the-project), and set up your framework, as
+described in [Framework integrations](../integrations.md).
+
+## Move classes into style()
+
+Replace each `className` string with a `style()` call that you spread onto the
+element:
+
+```tsx
+import { style } from "stillwind/react";
+
+export function Button() {
+  return <button {...style("rounded-md bg-brand px-4 py-2 text-white")}>Continue</button>;
+}
+```
+
+Import `style` from the entrypoint of the framework that renders the element.
+For a class that another stylesheet defines, pass it in a `class` field, such as
+`style("p-4", { class: "external-card" })`.
+
+A large codebase may have hundreds of `className` strings. Your coding agent can
+write a one-off codemod for your repository that converts them in one pass.
+
+## Replace class helpers
+
+`style()` and `style.cva()` replace the libraries that Tailwind projects use to
+build class strings:
+
+| Library                             | Stillwind                                 |
+| ----------------------------------- | ----------------------------------------- |
+| `clsx`, `classnames`                | `style()` with conditions                 |
+| `tailwind-merge`                    | Compose a base with new utilities         |
+| `cva` from class-variance-authority | `style.cva()` with the same configuration |
+
+### clsx and classnames
+
+Pass conditions as arguments:
+
+```tsx
+import { style } from "stillwind/react";
+
+export function SaveButton({ loading }: { loading: boolean }) {
+  return (
+    <button {...style("rounded-md bg-brand px-4 py-2 text-white", loading && "opacity-60")}>
+      Save
+    </button>
+  );
+}
+```
+
+Do not convert the object form of `clsx`. In `clsx({ "opacity-60": loading })`,
+each key is a class name. In `style()`, each key of an object is a variant, such
+as `"hover:"`. Rewrite each entry as `loading && "opacity-60"`.
+
+### tailwind-merge
+
+Remove `twMerge()` calls. Store the base style and pass it to another `style()`
+call. The compiler emits the new utilities after the base's CSS. They override
+competing declarations when the other cascade criteria, such as specificity
+and importance, are equal. See [Override a style](style.md#override-a-style)
+and [CSS ordering](../concepts/css-ordering.md).
+
+### cva
+
+Replace `cva(` with `style.cva(`, and import `VariantProps` from your framework's
+entrypoint:
+
+```tsx
+import { style, type VariantProps } from "stillwind/react";
+
+const button = style.cva("rounded-md px-4 py-2", {
+  variants: {
+    tone: {
+      neutral: "bg-gray-100",
+      primary: "bg-brand text-white",
+    },
+  },
+  defaultVariants: {
+    tone: "neutral",
+  },
+});
+
+export function Button({ tone }: VariantProps<typeof button>) {
+  return <button {...button({ tone })}>Continue</button>;
+}
+```
+
+`variants`, `defaultVariants`, and `compoundVariants` work as in
+class-variance-authority. Write each option value as a plain utility string,
+without `&&` or a ternary. The props that the factory returns cannot be passed
+to `style()` as a base. The [style.cva() reference](../macros/cva.md) lists the
+other differences.
+
+For new components, consider state variants and `data-*` attributes instead of
+options. See [Reusable styles](reusable-styles.md).
+
+## Move configuration
+
+Some Tailwind settings move from the stylesheet to `stillwind.config.ts`:
+
+| Tailwind                          | Stillwind                                    |
+| --------------------------------- | -------------------------------------------- |
+| `@config "./tailwind.config.js"`  | The `tailwind` field of the project          |
+| `@import "tailwindcss" important` | The `important` field of the project         |
+| `@source` and `source(...)`       | Not supported; see below                     |
+| `blocklist`                       | The `no-restricted-utilities` lint rule      |
+| `prefix(tw)`                      | Write utilities without `tw:`; see below     |
+| `theme(...)` on the import        | Not supported; define the tokens in `@theme` |
+
+The `tailwind` field accepts a Tailwind configuration object. Its `theme`,
+`presets`, `plugins`, `darkMode`, and `important` keys work as in Tailwind.
+Other keys have no effect. This field requires the `tailwindcss` package.
+
+Set `important` in one place only. Setting both `important` and
+`tailwind.important` is an error.
+
+Stillwind does not need the `tw:` class prefix, because it generates unique class
+names. Theme variables can still collide with other CSS in the page. To keep the
+`--tw-` names of `prefix(tw)`, set `themePrefix: "--tw-"` on the project. The
+prefix applies to the generated CSS, including `var(--color-brand)` in your
+stylesheet and in arbitrary values, so you can keep `var(--tw-color-brand)` or use
+the shorter name. JavaScript that reads or sets a theme variable by name must use
+the prefixed name.
+
+Stillwind does not support `@source`, including `@source inline()`, or a safelist,
+because only `style()` calls generate utilities. Tailwind classes inside a
+dependency also get no CSS. Write each utility that you need in a `style()` call
+in your own code.
+
+Stillwind ignores `@config`, `@source`, `@reference`, and import options in the
+stylesheet, and the CLI reports them with
+[ignored-tailwind-feature](../lints/ignored-tailwind-feature.md). Remove them after
+you move their settings. The same rule reports a v3 path in `theme()`, such as
+`theme(colors.red.500)`. Use `--theme(--color-red-500)` instead.
+
+Keep your `@plugin` rules and the `@import` rules of CSS packages.
+[Tailwind CSS compatibility](tailwind-compatibility.md#plugins-and-css-packages)
+lists the packages that the test suite covers.
+
+## Check the migrated code
+
+Run the [CLI checks](lint-adoption.md) over the migrated files. They
+report utilities that Stillwind cannot resolve and Tailwind features that it
+ignores. Then test the production build and your pages in the browser.

package/docs/guides/recommended-practices.md

@@ -0,0 +1,338 @@
+---
+title: "Recommended practices"
+description: "Keep styles next to their elements, reuse them through components, and avoid the mistakes that produce no CSS."
+---
+
+# Recommended practices
+
+This page collects the practices that keep a Stillwind project easy to change.
+It also lists the mistakes that silently produce no CSS. The examples use React.
+
+## Keep styles next to their elements
+
+Write the utilities in a `style()` call on the element that they style. When
+several places need the same styles, reuse them in this order:
+
+1. Extract a component of your framework, and keep the `style()` call on its
+   element. The styles stay next to the markup that they depend on.
+2. Define a custom utility in your stylesheet when a component does not fit,
+   such as for links inside other components' text. A utility is available in
+   every file of the project, so its effect is wider than a component's.
+3. Export a stored `style()` result. The styles then move away from the element
+   that uses them.
+
+When you use an imported style, spread it through `style()`:
+
+```tsx
+import { style } from "stillwind/react";
+
+import { card } from "./card";
+
+export function Panel() {
+  return <section {...style(card)}>…</section>;
+}
+```
+
+`{...style(card)}` shows that the element receives Stillwind styles, and you can
+add utilities in the same call. A plain `{...card}` hides this.
+
+## Spread style() onto the element
+
+Spread the result of `style()` onto the element. Do not read `className`,
+`class`, or `style` out of the result. The result can contain more than one
+prop, and its shape depends on the framework and on the inputs. If code needs a
+class string for another purpose, that code does not need `style()`, and a
+migration can leave it unchanged.
+
+Set custom properties in the `style()` call, such as
+`style("w-(--progress)", { "--progress": value })`. `style()` returns a `style`
+prop when it needs inline values, so a separate `style` prop on the same
+element can conflict with it. Set the `style` prop directly only on elements
+without a `style()` call. You can also use `style()` for an element that has
+custom properties and no utilities.
+
+## Express states with attributes
+
+Keep the same classes on an element, and let its attributes decide which styles
+apply:
+
+- For a state with an attribute, such as `disabled` or `aria-pressed`, use the
+  matching variant.
+- For an option without a matching attribute, set a `data-*` attribute and use
+  a `data-[…]:` variant.
+- For a value from a continuous range, set a custom property in the `style()`
+  call, and read it in a utility such as `w-(--progress)`.
+
+Use a condition such as `selected && "bg-blue-50"` only when no attribute fits.
+[Reusable styles](reusable-styles.md) shows each approach.
+
+Do not track in JavaScript a state that CSS can detect, such as hover, focus,
+or the width of a container. Use the matching variant, and keep component state
+for what the application needs.
+
+## Connect elements with refs
+
+When an element's style depends on another element, such as a hovered parent, a
+sibling, a container, or an anchor, connect them with a ref from
+`style.ref()`. Do not use `group-*`, `peer-*`, named containers, or hand-written
+parent and sibling selectors:
+
+```tsx
+import { style } from "stillwind/react";
+
+export function Card() {
+  const card = style.ref("card");
+  return (
+    <article {...style(card, "rounded-lg p-4")}>
+      <h2 {...style({ [card("hover")]: "text-blue-600" })}>Project</h2>
+    </article>
+  );
+}
+```
+
+A ref is a variable, so TypeScript reports a misspelled ref, and two components
+cannot collide on the same name. Anchors for anchor positioning use refs too.
+[Element relationships](element-relationships.md) covers siblings,
+containers, and anchors.
+
+## Define animations in their components
+
+Define keyframes with [style.keyframes()](../macros/keyframes.md) and view
+transitions with [style.viewTransition()](../macros/view-transition.md) in the
+code that uses them. Do not add global `@keyframes` rules or fixed
+`view-transition-name` values. The macros generate unique names, so you can
+add, move, or remove a component without checking other code.
+
+## Declare refs and animations in the smallest scope
+
+Declare a ref, keyframes, or a view transition in the smallest scope that
+contains all of its uses, as you would declare any other variable. Place the
+declaration next to those uses:
+
+- A declaration that one component uses belongs in that component's function.
+- A declaration that a callback uses, such as a `map()` callback, belongs in
+  that callback.
+- A declaration that several components of one module use belongs at the top
+  level of that module.
+- When other modules use a declaration, export it from one module, and import
+  it where you need it.
+
+Each declaration creates one name wherever you write it. A smaller scope limits
+where the variable is visible, and it does not create a new name for each render
+or call.
+
+## Express options with one of a fixed set of values
+
+For a prop that takes one of several values, such as a `type` or a `tone`,
+use one of these forms. Set the value as a `data-*` attribute, and write one
+variant group for each value:
+
+```tsx
+import { style } from "stillwind/react";
+
+export function Alert({ type }: { type: "info" | "warning" | "error" }) {
+  return (
+    <div
+      data-type={type}
+      {...style({
+        "": "rounded-md border p-4",
+        "data-[type=info]:": "border-sky-300 bg-sky-50",
+        "data-[type=warning]:": "border-amber-300 bg-amber-50",
+        "data-[type=error]:": "border-red-300 bg-red-50",
+      })}
+    />
+  );
+}
+```
+
+Or select the utilities with an object lookup:
+
+```tsx
+import { style } from "stillwind/react";
+
+export function Alert({ type }: { type: "info" | "warning" | "error" }) {
+  return (
+    <div
+      {...style(
+        "rounded-md border p-4",
+        {
+          info: "border-sky-300 bg-sky-50",
+          warning: "border-amber-300 bg-amber-50",
+          error: "border-red-300 bg-red-50",
+        }[type],
+      )}
+    />
+  );
+}
+```
+
+The attribute form keeps the classes static and changes a `data-*` attribute.
+The attribute also shows the value in the browser's developer tools and in test
+queries. The lookup form changes the classes and adds no attribute. In both
+forms, each value has its utilities in one place.
+
+The two forms produce different CSS:
+
+- The attribute form compiles into one class. The element always has this
+  class, and the attribute selectors decide which declarations apply.
+- The lookup form generates one class for each value. The lookup selects one of
+  these classes at runtime. In this example, the common styles add one more
+  class, which the element always has.
+
+In both forms, the styles for a value usually win over the common styles. In the
+attribute form, the attribute selector adds specificity, and the variant order
+places the rules after the common styles. In the lookup form, the compiler
+places the utilities that a condition selects after the unconditional
+utilities. More specific selectors and `!important` can still change the
+result. [CSS ordering](../concepts/css-ordering.md) describes these rules.
+
+## Group utilities by variant
+
+When several utilities share a variant, group them under one key instead of
+repeating the prefix:
+
+```tsx
+style({
+  "": "rounded-md bg-gray-100 px-4 py-2",
+  "hover:": "bg-gray-200 text-gray-900",
+  "focus-visible:": "outline-2 outline-offset-2 outline-accent",
+});
+
+// Or write the base utilities as a separate string.
+style("rounded-md bg-gray-100 px-4 py-2", {
+  "hover:": "bg-gray-200 text-gray-900",
+  "focus-visible:": "outline-2 outline-offset-2 outline-accent",
+});
+```
+
+The key `""` groups utilities without adding a variant. Each group shows the
+styles of one state, so readers do not need to collect the prefixed utilities
+from a long string.
+
+> **The key "" accepts the same inputs as a variant**
+>
+> The value of `""` accepts only the inputs that a variant group accepts. Write ref attachments,
+> `class` values, custom properties, and bases directly in the `style()` arguments, outside the
+> object. Otherwise the CLI reports
+> [invalid-rule-group-input](../lints/invalid-rule-group-input.md), and the compiler omits the whole
+> group. Ref projections, keyframes uses, and view-transition uses can appear in the group.
+
+## Keep values in the theme
+
+Define colors, spacing, and breakpoints as `@theme` tokens, and use the
+utilities that they add. Avoid arbitrary values such as `text-[#abcdef]` and
+`max-[768px]:`. [Design systems](design-systems.md) enables lint
+rules that report them.
+
+## Choose how to define themes
+
+When the application has only a light and a dark theme, define each color
+token with `light-dark()`, and let `color-scheme` select the value.
+[Design systems](design-systems.md) shows this setup.
+
+When the application can have more themes, `light-dark()` cannot express them.
+Define the tokens as ordinary values, and override them for each theme with an
+attribute selector. Set `color-scheme` in each theme, so that form controls and
+scroll bars match:
+
+```css
+@theme {
+  --color-surface: #ffffff;
+  --color-foreground: #202b45;
+}
+
+[data-theme="dark"] {
+  color-scheme: dark;
+  --color-surface: #1b263b;
+  --color-foreground: #e4edff;
+}
+
+[data-theme="sepia"] {
+  color-scheme: light;
+  --color-surface: #f4ecd8;
+  --color-foreground: #433422;
+}
+```
+
+Set `data-theme` on the root element, or on a container to theme part of the
+page. The utilities, such as `bg-surface`, stay the same in every theme.
+
+When a theme needs styles beyond its tokens, define a variant for it with
+[@custom-variant](../at-rules/custom-variant.md), and use the variant instead
+of a hand-written selector:
+
+```css
+@custom-variant theme-sepia (&:where([data-theme="sepia"], [data-theme="sepia"] *));
+```
+
+## Use breakpoints from the theme in JavaScript
+
+When JavaScript needs a breakpoint, get its media query with
+[style.media()](../macros/media.md) instead of repeating the value:
+
+```ts
+import { style } from "stillwind/react";
+
+const sidebar = window.matchMedia(style.media("sidebar"));
+```
+
+A query such as `matchMedia("(width >= 52.5rem)")` does not follow a later
+change of the breakpoint in the theme. Prefer a variant when CSS alone can make the
+change. [Responsive styles](responsive-styles.md) shows more uses.
+
+## Define utilities with @apply
+
+Write the body of a custom utility with `@apply`, and write its conditions as
+variants:
+
+```css
+@utility link {
+  @apply text-accent underline-offset-4 hover:underline;
+}
+```
+
+Do not write selectors or media queries by hand. The variants follow your
+theme, and they avoid differences that are easy to miss. For example, the
+`hover:` variant applies only on devices that can hover, while a plain `:hover`
+rule stays active after a tap on a touch screen. Inside a style rule, use
+[@variant](../at-rules/variant.md) instead of a condition.
+
+## Avoid separate CSS
+
+Write styles in `style()` calls and custom utilities, not in CSS files with
+your own class names. A custom utility works with every variant, such as
+`hover:link`, and a fixed class name does not. For a reusable condition, define
+a variant with [@custom-variant](../at-rules/custom-variant.md) instead of
+writing its selector in several rules.
+
+For HTML that you do not control, such as rendered Markdown, define the styles
+in a custom utility and apply it to the container. You can also use a Tailwind
+plugin such as `@tailwindcss/typography`.
+
+## Run the checks after each change
+
+Run `stillwind lint --fix` and `stillwind fmt` after you change styles, and fix
+the remaining findings. Add a suppression comment only for a deliberate
+exception, and give the reason. See
+[Checks in the editor and CI](lint-adoption.md).
+
+## Mistakes that produce no CSS
+
+The build succeeds in each of these cases, but the styles do not apply. Run
+`stillwind lint` to find most of them.
+
+- A class name outside `style()`, such as in a `className` string, gets no CSS.
+- A utility name that your code builds at runtime, such as `` `bg-${color}-600` ``,
+  gets no CSS. Write complete names, such as
+  `color === "red" ? "bg-red-600" : "bg-blue-600"`.
+- A `style()` call written directly inside another `style()` call contributes
+  nothing. Store the inner style in a variable first.
+- Custom properties in a base do not carry over to the styles that extend it.
+  Set them in the `style()` call that is spread onto the element.
+- Classes in the `class` field pass through without generated CSS.
+- A suppression comment hides a finding only. A misspelled utility still
+  produces no CSS.
+
+The compiler can evaluate the arguments of `style()` in any order, and it can
+skip arguments whose result is not used. Calculate values and perform effects
+before you call `style()`.