stillwind 0.0.0 → 0.1.0-rc.0

package/docs/guides/responsive-styles.md

@@ -0,0 +1,103 @@
+---
+title: "Responsive styles"
+description: "Name breakpoints once, and use them in utilities, authored CSS, and JavaScript."
+---
+
+# Responsive styles
+
+You want components to change layout at the same widths. Tailwind defines
+breakpoints in CSS, so a JavaScript check such as
+`matchMedia("(width >= 52.5rem)")` repeats the value. In Stillwind, you name each
+breakpoint once and use the name in both CSS and JavaScript.
+
+## Name breakpoints by layout role
+
+Name breakpoints after the layout change that they cause, instead of a device
+size:
+
+```css
+@import "stillwind";
+
+@theme {
+  --breakpoint-inline: 40rem;
+  --breakpoint-sidebar: 52.5rem;
+  --breakpoint-outline: 70rem;
+}
+
+.navigation {
+  @apply flex flex-col gap-3;
+  @variant inline {
+    @apply flex-row;
+  }
+}
+```
+
+Each `--breakpoint-*` token adds a variant, such as `sidebar:`. The default
+breakpoints, such as `md:`, remain available unless you remove them.
+
+## Use breakpoints in components
+
+```tsx
+import { style } from "stillwind/react";
+
+export function Layout() {
+  return (
+    <div {...style("flex flex-col gap-4 sidebar:flex-row")}>
+      <nav {...style("sidebar:w-64")}>Navigation</nav>
+      <main {...style("flex-1")}>Content</main>
+    </div>
+  );
+}
+```
+
+## Use breakpoints in authored CSS
+
+In a CSS rule, nest `@variant` with the breakpoint name, as in the `.navigation`
+rule above. In an `@utility` definition, use the variant in `@apply` instead,
+such as `@apply inline:flex-row`.
+
+## Use breakpoints in JavaScript
+
+`style.media()` returns the media query for a breakpoint name:
+
+```ts
+import { style } from "stillwind/react";
+
+const sidebar = window.matchMedia(style.media("sidebar"));
+const update = () => {
+  document.documentElement.dataset.sidebar = String(sidebar.matches);
+};
+sidebar.addEventListener("change", update);
+update();
+
+export function dispose() {
+  sidebar.removeEventListener("change", update);
+}
+```
+
+The compiler replaces `style.media("sidebar")` with the query string, so the
+JavaScript always matches the CSS. `matchMedia()` is a browser API, so call it on
+the client. Remove the listener when its component unmounts.
+
+To combine conditions, write them in one argument. To accept alternatives, pass
+several arguments:
+
+```ts
+import { style } from "stillwind/react";
+
+const enhanced = window.matchMedia(style.media("outline:motion-safe", "print"));
+```
+
+This query matches a viewport at least as wide as `outline` without a
+reduced-motion preference, or a printed page. `style.media()` accepts media
+conditions only. Element states such as `hover` are not media conditions.
+
+## Report widths outside your breakpoints
+
+The [no-arbitrary-breakpoints](../lints/no-arbitrary-breakpoints.md) rule
+reports widths written as values, such as `min-[713px]:`. See
+[Design systems](design-systems.md#report-values-outside-the-theme)
+to enable it.
+
+To respond to the width of a component instead of the viewport, use a container
+query. See [Element relationships](element-relationships.md#react-to-a-containers-size).

package/docs/guides/reusable-styles.md

@@ -0,0 +1,110 @@
+---
+title: "Reusable styles"
+description: "Share a base style, and express states and options with variants instead of toggled classes."
+---
+
+# Reusable styles
+
+You want components to share styles and to change their look by state or by
+option. In Stillwind, you share a base style, and you express states and options
+with variants. The element keeps the same classes, and its attributes decide
+which styles apply.
+
+## Share a base style
+
+Store a `style()` result, and pass it to other `style()` calls. You can export
+the base and import it in other modules:
+
+```tsx
+import { style } from "stillwind/react";
+
+export const button = style(
+  "inline-flex rounded-md bg-gray-100 px-4 py-2 font-medium text-gray-900",
+);
+const primaryButton = style(button, "bg-blue-600 text-white");
+const dangerButton = style(button, "bg-red-600 text-white");
+
+export function Actions() {
+  return (
+    <div {...style("flex gap-2")}>
+      <button {...primaryButton}>Save</button>
+      <button {...dangerButton}>Delete</button>
+    </div>
+  );
+}
+```
+
+In this example, the derived styles replace the base's background and text
+colors. Their CSS comes after the base's CSS, and their selectors have equal
+specificity. The order of the class names does not affect the result.
+
+A base's `hover:` selector can be more specific than a plain class in the
+derived style. [CSS ordering](../concepts/css-ordering.md) explains variants,
+conditions, and multiple bases.
+
+A base passes on its classes only. Custom properties such as
+`{ "--progress": value }` in the base do not carry over, and the CLI reports
+them. Set custom properties in the `style()` call that is spread onto the element.
+
+## Express states with variants
+
+Set the state as an attribute, and style it with a variant:
+
+```tsx
+import { style } from "stillwind/react";
+
+export function ToggleButton({ pressed }: { pressed: boolean }) {
+  return (
+    <button
+      aria-pressed={pressed}
+      {...style(
+        "rounded-md bg-gray-100 px-4 py-2",
+        "aria-pressed:bg-blue-600 aria-pressed:text-white",
+      )}
+    >
+      Bold
+    </button>
+  );
+}
+```
+
+The `aria-pressed` attribute is needed for accessibility anyway. Use variants
+such as `disabled:`, `aria-expanded:`, and `open:` in the same way. The element
+always has the same classes, so you do not need to think about which toggled
+class wins.
+
+## Express options with data attributes
+
+For an option without a matching ARIA attribute, set a `data-*` attribute:
+
+```tsx
+import { style } from "stillwind/react";
+
+export function Badge({ tone, label }: { tone: "neutral" | "danger"; label: string }) {
+  return (
+    <span
+      data-tone={tone}
+      {...style(
+        "rounded-full bg-gray-100 px-2 text-gray-900",
+        "data-[tone=danger]:bg-red-600 data-[tone=danger]:text-white",
+      )}
+    >
+      {label}
+    </span>
+  );
+}
+```
+
+The attribute also shows the option in the browser's developer tools and in
+test queries.
+
+For a value from a continuous range, such as a width or a progress percentage,
+set a custom property instead. See
+[Use runtime values](style.md#use-runtime-values).
+
+## Migrate CVA components
+
+`style.cva()` accepts the configuration of `cva` from class-variance-authority.
+Use it to migrate existing CVA components. See
+[Replace class helpers](migrating-from-tailwind.md#replace-class-helpers)
+and the [style.cva() reference](../macros/cva.md).

package/docs/guides/style.md

@@ -0,0 +1,181 @@
+---
+title: "The basics of style()"
+description: "Apply utilities, variants, conditions, overrides, and runtime values to an element."
+---
+
+# The basics of style()
+
+`style()` takes Tailwind CSS v4 utilities and returns props for an element.
+You spread the props onto the element instead of writing a `className` string.
+This page uses React. For other frameworks, import `style` from the entrypoint
+listed in [Framework integrations](../integrations.md).
+
+## Apply utilities
+
+```tsx
+import { style } from "stillwind/react";
+
+export function Workspace() {
+  return (
+    <section {...style("flex flex-col gap-4 rounded-lg bg-white p-6")}>
+      <h2 {...style("text-xl font-semibold")}>Your workspace</h2>
+      <p {...style("text-gray-600")}>Keep your component styles together.</p>
+    </section>
+  );
+}
+```
+
+The compiler reads the utilities at build time and generates their CSS.
+In React, `style()` returns a `className` prop.
+
+Utilities and variants come from the stylesheet that `stillwind.config.ts`
+selects. A token that you add to `@theme` adds utilities, such as `bg-accent`
+for `--color-accent`.
+
+## Add variants
+
+Write variants as in Tailwind:
+
+```tsx
+import { style } from "stillwind/react";
+
+export function SaveButton() {
+  return (
+    <button {...style("rounded-md bg-blue-600 px-4 py-2 text-white hover:bg-blue-700 md:px-6")}>
+      Save changes
+    </button>
+  );
+}
+```
+
+To apply several utilities under the same variant, use an object. Each key is
+a variant followed by a colon:
+
+```tsx
+import { style } from "stillwind/react";
+
+export function Link() {
+  return (
+    <a href="/docs" {...style("text-blue-600", { "hover:": "text-blue-800 underline" })}>
+      Documentation
+    </a>
+  );
+}
+```
+
+## Style states
+
+When the element has an attribute for the state, use a variant:
+
+```tsx
+import { style } from "stillwind/react";
+
+export function SaveButton({ loading }: { loading: boolean }) {
+  return (
+    <button
+      disabled={loading}
+      {...style(
+        "rounded-md bg-blue-600 px-4 py-2 text-white disabled:cursor-wait disabled:opacity-60",
+      )}
+    >
+      {loading ? "Saving…" : "Save changes"}
+    </button>
+  );
+}
+```
+
+The element keeps the same classes, and the browser applies the `disabled:`
+styles while the button is disabled. [Reusable styles](reusable-styles.md)
+shows the same approach with `aria-*` and `data-*` attributes.
+
+When no attribute represents the state, pass a condition and a string, as with `clsx`:
+
+```tsx
+import { style } from "stillwind/react";
+
+export function Row({ selected }: { selected: boolean }) {
+  return <li {...style("px-4 py-2", selected && "bg-blue-50 font-medium")}>Inbox</li>;
+}
+```
+
+The compiler generates CSS for both strings. At runtime, the condition decides
+whether the element gets `bg-blue-50 font-medium`.
+
+Write complete utility names in the source. The compiler cannot generate CSS for
+a name that your code builds at runtime, such as `` `bg-${color}-600` ``.
+Choose between complete names instead, such as
+`color === "red" ? "bg-red-600" : "bg-blue-600"`.
+
+## Override a style
+
+Store a `style()` result in a variable, and pass it to another `style()` call.
+The compiler places CSS for the new utilities after the base's CSS:
+
+```tsx
+import { style } from "stillwind/react";
+
+const button = style("rounded-md bg-blue-600 px-4 py-2 text-white");
+const dangerButton = style(button, "bg-red-600");
+
+export function DeleteButton() {
+  return <button {...dangerButton}>Delete</button>;
+}
+```
+
+In this example, `dangerButton` has a red background because both background
+rules use equally specific selectors. The order of the class names does not
+affect the result. You can export a stored style and use it in other modules.
+
+More specific selectors and `!important` can change which declaration wins.
+See [CSS ordering](../concepts/css-ordering.md) for variants, conditions, and multiple
+bases.
+
+Store the inner style in a variable first. A `style()` call written directly
+inside another, such as `style(style("p-4"), "text-sm")`, is not supported.
+[Reusable styles](reusable-styles.md) covers shared styles and
+component options in more detail.
+
+## Use runtime values
+
+For a value that is known only at runtime, set a CSS custom property and read it
+in a utility:
+
+```tsx
+import { style } from "stillwind/react";
+
+export function Progress({ value }: { value: number }) {
+  return (
+    <div {...style("h-2 w-(--progress) rounded-full bg-blue-600", { "--progress": `${value}%` })} />
+  );
+}
+```
+
+The utility `w-(--progress)` stays the same, so its CSS is generated at build
+time. Only the value of `--progress` changes at runtime.
+
+## Add classes from other stylesheets
+
+To add a class that another stylesheet defines, pass it in a `class` field:
+
+```tsx
+import { style } from "stillwind/react";
+
+export function Card({ className }: { className?: string }) {
+  return <article {...style("rounded-lg p-4", { class: className })} />;
+}
+```
+
+Stillwind passes these classes through and does not generate CSS for them.
+
+## Keep arguments free of side effects
+
+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,
+such as state updates or I/O, before you call `style()`.
+
+## Next steps
+
+- [Reusable styles](reusable-styles.md) shares styles and defines component options.
+- [Responsive styles](responsive-styles.md) names breakpoints and uses them in JavaScript.
+- [Checks in the editor and CI](lint-adoption.md) finds misspelled utilities and other mistakes.
+- [The style() reference](../macros/style.md) lists every accepted input.

package/docs/guides/tailwind-compatibility.md

@@ -0,0 +1,126 @@
+---
+title: "Tailwind CSS compatibility"
+description: "Check which Tailwind CSS v4 features, plugins, and CSS packages work in Stillwind, and what Stillwind does differently by design."
+---
+
+# Tailwind CSS compatibility
+
+Stillwind supports the utilities, variants, theme, CSS directives, and plugins of
+Tailwind CSS v4. To move a project, follow
+[Migrating from Tailwind CSS](migrating-from-tailwind.md). This page
+lists what works, how Stillwind checks it, and where Stillwind differs.
+
+## What works
+
+| Tailwind feature                        | Support                                                              |
+| --------------------------------------- | -------------------------------------------------------------------- |
+| Default theme and preflight             | Included in `@import "stillwind"`                                    |
+| Utilities and variants                  | Supported, including arbitrary values, modifiers, and `!`            |
+| `@theme`, `@utility`, `@custom-variant` | Supported                                                            |
+| `@apply`, `@variant`                    | Supported                                                            |
+| `--theme()`, `--spacing()`, `--alpha()` | Supported                                                            |
+| `theme(--color-red-500)`                | Supported; v3 paths such as `theme(colors.red.500)` are not          |
+| `@plugin` with JavaScript plugins       | Supported; see [Plugins and CSS packages](#plugins-and-css-packages) |
+| `@import` of CSS packages               | Supported; see [Plugins and CSS packages](#plugins-and-css-packages) |
+| Tailwind configuration                  | Set the `tailwind` field of the project in `stillwind.config.ts`     |
+
+## How Stillwind checks compatibility
+
+The test suite compares Stillwind with the Tailwind compiler. It runs both
+compilers on the same input and fails when their results differ:
+
+- For utilities and variants, it compares the generated CSS for each class in
+  Tailwind's public class list and in its variant list.
+- For plugins and CSS packages, it builds the same stylesheet with both compilers
+  and compares the computed styles in Chrome.
+
+The declarations inside a rule can stand in a different order from Tailwind's, as
+[CSS ordering](../concepts/css-ordering.md) describes. The order of two declarations
+that can affect each other stays the same, so the computed styles do not change.
+
+## Plugins and CSS packages
+
+Tailwind CSS v4 plugins work in Stillwind in principle. The test suite runs the
+following packages in Vite development and production builds and in Rspack
+production builds. It also compares their output with Tailwind.
+
+Load these packages with `@plugin`:
+
+| Package                             | Example                                     |
+| ----------------------------------- | ------------------------------------------- |
+| `@tailwindcss/typography`           | `prose`, `prose-lg`, `prose-headings:`      |
+| `@tailwindcss/forms`                | `form-input`, and the base styles of forms  |
+| `daisyui`                           | `btn`, `card`, `badge`, themes              |
+| `tailwindcss-animate`               | `animate-in`, `fade-in-50`                  |
+| `tailwindcss-motion`                | `motion-preset-fade`, `motion-duration-700` |
+| `tailwind-scrollbar`                | `scrollbar-thin`, `scrollbar-thumb-brand`   |
+| `tailwindcss-radix`                 | `radix-state-open:`                         |
+| `tailwindcss-react-aria-components` | `selected:`                                 |
+| `@headlessui/tailwindcss`           | `ui-open:`                                  |
+| `@iconify/tailwind4`                | `icon-[lucide--home]`                       |
+
+Load these packages with `@import`:
+
+| Package                      | Example                                |
+| ---------------------------- | -------------------------------------- |
+| `tw-animate-css`             | `animate-in`, `fade-in-50`             |
+| `tailwindcss-animated`       | `animate-fade`, `animate-duration-700` |
+| `tailwindcss-intersect`      | `intersect:`                           |
+| `tailwindcss-safe-area`      | `pt-safe-or-4`                         |
+| `tailwind-scrollbar-hide/v4` | `scrollbar-hide`                       |
+| `preline/variants.css`       | `hs-dropdown-open:`                    |
+
+Other plugins can use the same features. [@plugin](../at-rules/plugin.md#tailwind-css-plugins)
+lists the supported plugin API. JavaScript plugins need the `tailwindcss` package,
+and CSS packages do not.
+
+The tests cover CSS. They do not run the JavaScript of a package, such as the
+components of Preline. Plugins have no browser test with webpack or Next.js. Test
+these combinations in your application.
+
+### Class names that a plugin's selectors use
+
+A plugin can select an element by a fixed class name. For example, the rules of
+`prose` skip elements inside `not-prose`. `style()` keeps such a class in the
+`class` attribute, so `style("not-prose")` adds the class `not-prose`. The class
+keeps its name only without variants, so
+[invalid-marker-use](../lints/invalid-marker-use.md) reports `hover:not-prose`.
+
+## What Stillwind does not support
+
+These differences come from the design of Stillwind. No setting changes them.
+
+### Classes outside style()
+
+Only `style()` calls generate utilities. Stillwind does not scan files, so these
+features have no replacement:
+
+- `@source`, `@source inline()`, and `source(...)` on `@import`
+- A safelist of class names
+- Tailwind classes inside a dependency
+- Utility classes that JavaScript adds at runtime, such as `` `bg-${color}-600` ``
+
+Write each utility that you need in a `style()` call in your own code. For HTML
+that you do not control, see
+[Avoid separate CSS](recommended-practices.md#avoid-separate-css).
+
+### The tw: class prefix
+
+Stillwind generates unique class names, so utilities do not need a prefix. Write
+`p-4` instead of `tw:p-4`. Theme variables can still collide with other CSS in the
+page. To prefix them, set `themePrefix` on the project, as
+[Migrating from Tailwind CSS](migrating-from-tailwind.md#move-configuration)
+describes. In a plugin, `prefix()` returns the class name unchanged.
+
+### Other differences
+
+| Tailwind                                   | Stillwind                                                                         |
+| ------------------------------------------ | --------------------------------------------------------------------------------- |
+| `@reference`                               | Ignored; `@import` the stylesheet from the stylesheet of the project              |
+| `theme(colors.red.500)`                    | Stays in the CSS, where browsers reject it; use `--theme(--color-red-500)`        |
+| `blocklist`                                | Has no effect; use the `no-restricted-utilities` lint rule                        |
+| Utilities that generate invalid CSS        | Rejected, such as `justify-baseline`, because `justify-content` has no such value |
+| `addVariant()` with the v3 `:merge()` form | Skipped, as in Tailwind CSS v4                                                    |
+
+[ignored-tailwind-feature](../lints/ignored-tailwind-feature.md) reports the
+features in your stylesheet that have no effect.

package/docs/guides/view-transitions.md

@@ -0,0 +1,84 @@
+---
+title: "View transitions"
+description: "Style view transition snapshots in the component, and give each item a stable name."
+---
+
+# View transitions
+
+You want an item to animate between two states of the page with the browser's
+View Transition API. In plain CSS, you write `view-transition-name` and the
+`::view-transition-*` rules in a global stylesheet, and you keep every name
+unique by hand. In Stillwind, you define the transition in the component and
+name each item with a key.
+
+## Define the transition and name each item
+
+```tsx
+import { style } from "stillwind/react";
+
+const productTransition = style.viewTransition({
+  old: "duration-150 motion-reduce:duration-0",
+  new: "delay-150 duration-150 motion-reduce:delay-0 motion-reduce:duration-0",
+});
+
+export function Product({ id, name }: { id: string; name: string }) {
+  return <article {...style(productTransition.for(id), "rounded-lg p-4")}>{name}</article>;
+}
+```
+
+`style.viewTransition()` defines the styles of the snapshots. Each field styles
+one pseudo-element:
+
+| Field       | Pseudo-element                   |
+| ----------- | -------------------------------- |
+| `group`     | `::view-transition-group()`      |
+| `imagePair` | `::view-transition-image-pair()` |
+| `old`       | `::view-transition-old()`        |
+| `new`       | `::view-transition-new()`        |
+
+Timing utilities in these fields set animation properties. For example,
+`duration-150` sets `animation-duration`.
+
+`.for(id)` gives the element a view transition name from the key. Use a key
+that stays the same for the same item before and after the update, such as a
+database ID. Two items on the page at the same time need different keys.
+
+## Start the transition
+
+Stillwind generates the styles and names. Your code starts the transition:
+
+```ts
+export function navigate(update: () => void) {
+  if (document.startViewTransition) {
+    document.startViewTransition(update);
+  } else {
+    update();
+  }
+}
+```
+
+Call `update` the way your framework normally renders a change. Browsers without
+the View Transition API run the update without animation.
+
+## Give each element one name
+
+Use `.for()` once for each element, in one `style()` call. To combine several
+transitions on one element, pass the others without `.for()`:
+
+```tsx
+import { style } from "stillwind/react";
+
+const fade = style.viewTransition({ old: "duration-150" });
+const slide = style.viewTransition({ new: "duration-300" });
+
+export function Card({ id }: { id: string }) {
+  return <article {...style(fade, slide.for(id))}>Card</article>;
+}
+```
+
+The CLI reports a `style()` call that applies a transition without `.for()`, a
+call with two `.for()` calls, and transitions split across separate `style()`
+calls. It cannot check that keys are unique across the whole page.
+
+The [style.viewTransition() reference](../macros/view-transition.md) covers
+dynamic keys and the generated CSS.