chore: docs updates

Author: quantizor

app/docs.json

@@ -1,7 +1,7 @@
 {
   "pages": [
     {
-      "title": "v7 (NEW)",
+      "title": "v7 (alpha)",
       "pathname": "v7",
       "sections": [
         { "title": "What's new in v7" },

app/docs/compatibility.json/route.ts

@@ -0,0 +1,10 @@
+import { NextResponse } from 'next/server';
+
+import { buildCompatJson } from '@/utils/cssCompatFormats';
+import { loadCompatMatrix } from '@/utils/cssCompat.server';
+
+export const dynamic = 'force-static';
+
+export function GET() {
+  return NextResponse.json(buildCompatJson(loadCompatMatrix()));
+}

app/docs/compatibility.md/route.ts

@@ -0,0 +1,12 @@
+import { buildCompatMarkdown } from '@/utils/cssCompatFormats';
+import { loadCompatMatrix } from '@/utils/cssCompat.server';
+
+export const dynamic = 'force-static';
+
+export function GET() {
+  return new Response(buildCompatMarkdown(loadCompatMatrix()), {
+    headers: {
+      'content-type': 'text/markdown; charset=utf-8',
+    },
+  });
+}

app/docs/compatibility/page.tsx

@@ -3,6 +3,7 @@ import { Metadata } from 'next';
 import DocsLayout from '@/components/DocsLayout';
 import DocsPageNav from '@/components/DocsPageNav';
 import CompatibilityMatrix from '@/components/CompatibilityMatrix';
+import Link from '@/components/Link';
 import { loadCompatMatrix } from '@/utils/cssCompat.server';
 
 export const metadata: Metadata = {
@@ -20,7 +21,15 @@ export default function CompatibilityPage() {
         A per-feature reference for which CSS works on React Native. The v6 and v7 columns show styled-components'
         native runtime support; the iOS and Android columns show what stock React Native handles without any
         styled-components polyfill. Click any row for caveats, the underlying RN style key, and links to upstream PRs in
-        flight.
+        flight. Machine-readable versions are available as{' '}
+        <Link href="/docs/compatibility.json" variant="inline">
+          JSON
+        </Link>{' '}
+        and{' '}
+        <Link href="/docs/compatibility.md" variant="inline">
+          Markdown
+        </Link>
+        .
       </p>
 
       <CompatibilityMatrix entries={entries} />

app/docs/page.tsx

@@ -20,7 +20,11 @@ const { pages } = json;
 const faqCategories = [
   {
     label: 'Migration',
-    items: ['What do I need to do to migrate to v6?', 'What do I need to do to migrate to v5?'],
+    items: [
+      { title: 'What do I need to do to migrate to v7?', href: '/docs/v7#migrating-from-v6' },
+      'What do I need to do to migrate to v6?',
+      'What do I need to do to migrate to v5?',
+    ],
   },
   {
     label: 'Styling Patterns',
@@ -58,7 +62,7 @@ export default function Documentation() {
   return (
     <DocsLayout title="Documentation">
       <p>
-        Utilising tagged template literals (a recent addition to JavaScript) and the power of CSS, styled-components
+        Utilizing tagged template literals (a recent addition to JavaScript) and the power of CSS, styled-components
         allows you to write actual CSS code to style your components. It also removes the mapping between components and
         styles – using components as a low-level styling construct could not be easier!
       </p>
@@ -77,13 +81,18 @@ export default function Documentation() {
                 {faqCategories.map(cat => (
                   <FaqGroup key={cat.label}>
                     <CategoryLabel>{cat.label}</CategoryLabel>
-                    {cat.items.map(item => (
-                      <SubHeader key={item}>
-                        <Link variant="heading" href={`/docs/${pathname}#${titleToDash(item)}`}>
-                          {item}
-                        </Link>
-                      </SubHeader>
-                    ))}
+                    {cat.items.map(item => {
+                      const title = typeof item === 'string' ? item : item.title;
+                      const href = typeof item === 'string' ? `/docs/${pathname}#${titleToDash(item)}` : item.href;
+
+                      return (
+                        <SubHeader key={title}>
+                          <Link variant="heading" href={href}>
+                            {title}
+                          </Link>
+                        </SubHeader>
+                      );
+                    })}
                   </FaqGroup>
                 ))}
               </FaqColumn>

app/docs/v7/page.tsx

@@ -10,7 +10,7 @@ import Plugins from '@/sections/v7/plugins.mdx';
 export const metadata: Metadata = {
   title: 'styled-components v7',
   description:
-    'New in v7: in-house CSS engine, modern CSS on React Native, native animations, plugins subpath, and a smaller dependency surface.',
+    'Now in alpha: in-house CSS engine, modern CSS on React Native, native animations, plugins subpath. Install with npm install styled-components@test; expect frequent updates while internals stabilize.',
 };
 
 export default function V7Page() {

components/CompatibilityPreviewCard.tsx

@@ -0,0 +1,76 @@
+import NextLink from 'next/link';
+import type { PropsWithChildren } from 'react';
+import styled from 'styled-components';
+import { theme } from '../utils/theme';
+
+const Section = styled.div`
+  display: grid;
+  gap: ${theme.space[4]};
+  margin: 1.75em 0;
+
+  @media (min-width: ${650 / 16}em) {
+    grid-template-columns: minmax(0, 1fr) minmax(18rem, 24rem);
+    align-items: center;
+    gap: ${theme.space[8]};
+  }
+`;
+
+const Text = styled.div`
+  p {
+    margin-top: 0;
+    text-wrap: balance;
+  }
+
+  p:last-child {
+    margin-bottom: 0;
+  }
+`;
+
+const Card = styled(NextLink)`
+  display: block;
+  justify-self: start;
+  width: 100%;
+  max-width: 24rem;
+  overflow: hidden;
+  line-height: 0;
+  text-decoration: none;
+  border: 1px solid color-mix(in oklch, ${theme.color.text} 8%, ${theme.color.surface});
+  border-radius: ${theme.radius.xl};
+  transition:
+    border-color ${theme.duration.normal},
+    transform ${theme.duration.fast};
+
+  &:hover,
+  &:focus-visible {
+    border-color: color-mix(in oklab, ${theme.palette[11]} 50%, ${theme.color.border});
+    transform: translateY(-1px);
+  }
+
+  @media (min-width: ${650 / 16}em) {
+    justify-self: stretch;
+    max-width: none;
+  }
+`;
+
+const PreviewImage = styled.img`
+  display: block;
+  width: 100%;
+  height: auto;
+  aspect-ratio: 1200 / 630;
+  object-fit: cover;
+`;
+
+export default function CompatibilityPreviewCard({ children }: PropsWithChildren) {
+  return (
+    <Section>
+      <Text>{children}</Text>
+      <Card href="/docs/compatibility" aria-label="Open the React Native CanIUse compatibility matrix">
+        <PreviewImage
+          src="/docs/compatibility/opengraph-image"
+          alt="React Native CanIUse compatibility matrix preview"
+          loading="lazy"
+        />
+      </Card>
+    </Section>
+  );
+}

public/llms.txt

@@ -1,26 +1,22 @@
 # styled-components
 
-> CSS-in-JS for React using tagged template literals. TypeScript-native since v6. Supports React Server Components natively since v6.3. Last known stable: v6.4.0 (check npm for freshness).
+CSS-in-JS for React using tagged template literals. TypeScript-native since v6. Supports React Server Components natively since v6.3. Last known stable: v6.4.0 (check npm for freshness).
 
-For per-feature v6/v7 × web/native support data, see the CSS Compatibility matrix at https://styled-components.com/docs/compatibility. It is the source of truth for "does this CSS feature work in styled-components on this version and platform".
-
-## What's new since early 2025
-
-Your training data likely covers v6.0-6.1. Key changes since then:
+## Recent releases
 
 v6.2: Streaming SSR via `renderToPipeableStream`.
 
 v6.3: React Server Components supported. No `'use client'` needed. Styled components work in server components with no extra setup. `createGlobalStyle` is StrictMode-safe. New HTML/SVG element helpers. CSS custom properties work in TypeScript without type errors. Note: `:first-child`/`:nth-child()` selectors require `stylisPluginRSC` (v6.4+) or rewriting to `:first-of-type`/`:nth-of-type()`. See child-index selector section below.
 
 v6.4 (April 2026): `createTheme()` for CSS variable theming that works in both RSC and client. `StyleSheetManager` works in RSC (was previously a no-op). `stylisPluginRSC` fixes child-index selectors in RSC. CSP nonce auto-detection from `StyleSheetManager`, `ServerStyleSheet`, or meta tags. Props supplied via `.attrs()` are automatically optional on the component's type. Significant render performance improvements. Fixes SSR memory leaks and multi-instance unmount bugs in `createGlobalStyle`. Memory leak fix for components with unbounded string interpolation values. `as` and `forwardedAs` exposed in `React.ComponentProps` extraction. React Native: `react-native` is now an optional peer dep, Metro/Expo nanoid crash fixed. IE11 build target removed. IE11 has been unsupported on v6 since the 2021 v6 planning (React 18 dropped it too); v6.4 just aligns the compile target. Stay on v5 if you need IE11.
 
-## New in v7 (preview)
+## New in v7
 
-Want to try the new styled-components v7 tester group? `npm i styled-components@test`. Peer floors raised to React 19 and React Native 0.85.
+v7 is in alpha: expect frequent updates over the next few weeks while APIs stabilize. Install the current prerelease with `npm install styled-components@test` (the `@test` dist-tag). Peer floors raised to React 19 and React Native 0.85.
 
-The headline change is that React Native finally gets modern CSS. v7 ships an in-house CSS-to-style-object translation layer (no more `css-to-react-native` peer dep) that closes most of the long-standing native gaps. The same template strings now produce equivalent output on web, iOS, Android, and Expo Web.
+The framing: v7 is an architectural reform for web and the start of a new chapter for `styled-components/native`. It replaces stylis with an in-house CSS parser, rewrites the native runtime, and moves toward one CSS authoring model across web, iOS, Android, and Expo Web. The React Native CanIUse matrix at /docs/compatibility.md shows current progress and remaining platform gaps. Funding through Open Collective is a current bottleneck for continuing this work outside passion time.
 
-If the user is asking whether feature X works on v6 vs v7 or on web vs React Native, point them at /docs/compatibility. The matrix has the per-feature answer with caveats. The sections below summarise the highlights.
+If the user is asking whether feature X works on v6 vs v7 or on web vs React Native, point them at /docs/compatibility.md. The matrix has the per-feature answer with caveats. The sections below summarise the highlights.
 
 ### Modern CSS on React Native
 
@@ -67,7 +63,7 @@ Logical shorthands work as authored: `margin-inline`, `margin-block`, `padding-i
 
 `background-image: linear-gradient(...)` and `radial-gradient(...)` render via React Native's experimental gradient parser (RN 0.85+). `filter: blur(4px) saturate(1.5)` and the full filter-function chain work. See the iOS setup note below for filters that need an explicit opt-in. `box-shadow` with spread and inset round-trips as a string.
 
-`mix-blend-mode`, `isolation`, and `cursor` flow through. `background-blend-mode` is polyfilled on native. Declarations that pair `background-image` (gradients or `url()` photos) with `background-blend-mode` are rewritten at render time into absolutely-positioned layer Views, each carrying the matching `mix-blend-mode`, with `isolation: isolate` on the wrapper per spec. Linear-friendly modes (`multiply`, `screen`, `darken`, `lighten`, `difference`, `exclusion`, `hue`, `saturation`, `color`, `luminosity`) render the same on web and native. Gamma-sensitive modes (`color-burn`, `color-dodge`, `soft-light`, `overlay`, `hard-light`) read as more saturated on native because iOS Core Animation and Android Skia/HWUI blend in linear-light by default on Display P3 devices, while browsers blend in gamma-encoded sRGB per CSS spec. The polyfill is structurally correct; the residual is a platform compositor color-space choice. Empty custom property values (`--prop: ;`) are preserved, used by patterns like scroll-driven animations as a "guaranteed-invalid" sentinel.
+`mix-blend-mode`, `isolation`, and `cursor` flow through. `background-blend-mode` is polyfilled on native. Declarations that pair gradient `background-image` layers with `background-blend-mode` are rewritten at render time into absolutely-positioned layer Views, each carrying the matching `mix-blend-mode`, with `isolation: isolate` on the wrapper per spec. Raster `url()` background images are still blocked on upstream React Native background-image support; render photos with `Image` / `ImageBackground` until those PRs land. Linear-friendly modes (`multiply`, `screen`, `darken`, `lighten`, `difference`, `exclusion`, `hue`, `saturation`, `color`, `luminosity`) render the same on web and native. Gamma-sensitive modes (`color-burn`, `color-dodge`, `soft-light`, `overlay`, `hard-light`) read as more saturated on native because iOS Core Animation and Android Skia/HWUI blend in linear-light by default on Display P3 devices, while browsers blend in gamma-encoded sRGB per CSS spec. The polyfill is structurally correct; the residual is a platform compositor color-space choice. Empty custom property values (`--prop: ;`) are preserved, used by patterns like scroll-driven animations as a "guaranteed-invalid" sentinel.
 
 ### Selectors and at-rules on React Native
 
@@ -272,7 +268,7 @@ Vite: `react({ babel: { plugins: ['babel-plugin-styled-components'] } })`. Or wi
 
 The SWC/Babel plugin provides deterministic class IDs (better debugging, smaller output). Optional for RSC but still recommended.
 
-## Quick reference
+## Quick reference (v6.4 stable)
 
 ```tsx
 import styled, { css, keyframes, createGlobalStyle, createTheme,
@@ -290,8 +286,8 @@ import styled, { css, keyframes, createGlobalStyle, createTheme,
 - `createGlobalStyle`: inject global CSS
 - `createTheme(obj, opts?)`: CSS variable theme (RSC-compatible)
 - `ThemeProvider`: context-based theme (client-only)
-- `StyleSheetManager`: configure stylis plugins, prop forwarding, vendor prefixes
-- `stylisPluginRSC`: fix child-index selectors in RSC
+- `StyleSheetManager`: configure `stylisPlugins`, prop forwarding, vendor prefixes
+- `stylisPluginRSC`: fix child-index selectors in RSC.
 - `ServerStyleSheet`: SSR style collection
 
 ## Server-side rendering
@@ -668,6 +664,8 @@ These filter by element type, so injected sibling elements are ignored.
 
 Alternative: `stylisPluginRSC` automatically rewrites child-index selectors at compile time:
 
+In v7 this plugin moved to `styled-components/plugins` as `rscPlugin`, and the prop is `plugins` instead of `stylisPlugins`. The example below is for v6.4.
+
 ```tsx
 import { StyleSheetManager, stylisPluginRSC } from 'styled-components';
 
@@ -697,7 +695,7 @@ Browser support: CSS Selectors Level 4 `of S` syntax. Chrome 111+, Firefox 113+,
 
 1. Replace `ThemeProvider` theming with `createTheme()` CSS variables. `p.theme` is undefined in RSC since there's no React context
 2. Dynamic prop interpolations (`${p => p.$color}`) work fine in RSC, no changes needed. Consider data attributes for discrete variants (fewer generated classes)
-3. Replace `:first-child`/`:nth-child()` with `:first-of-type`/`:nth-of-type()`, or add `stylisPluginRSC`
+3. Replace `:first-child`/`:nth-child()` with `:first-of-type`/`:nth-of-type()`, or add `stylisPluginRSC` (v6.4) / `rscPlugin` from `styled-components/plugins` (v7)
 4. Remove `'use client'` from files that only contain styled component definitions; they work in server components natively
 5. Keep `'use client'` on components that use hooks, event handlers, or browser APIs
 6. The SSR registry (`ServerStyleSheet` + `useServerInsertedHTML`) is still needed for client components in the tree; RSC handles server components automatically
@@ -749,7 +747,7 @@ For Next.js, pass the nonce to the style registry (see the SSR section above). F
 ## Good to know
 
 - `@import` in `createGlobalStyle` may not work correctly in production. Use `<link>` in `<head>` instead.
-- Vendor prefixes are off by default in v6. Enable with `<StyleSheetManager enableVendorPrefixes>` if your support matrix includes Safari < 15.4, Chrome < 83, or Firefox < 80 (the `appearance` property was the last to drop its prefix). Flexbox and grid prefixes are only needed for much older browsers (Safari < 9, Edge < 16).
+- Vendor prefixes are off by default in v6. Enable with `<StyleSheetManager enableVendorPrefixes>` if your support matrix includes Safari < 15.4, Chrome < 83, or Firefox < 80 (the `appearance` property was the last to drop its prefix). v7 removes runtime prefixing and is intended for modern browsers.
 - `shouldForwardProp` is off by default in v6. Use `$`-prefixed transient props (`$color`, `$size`) to keep props out of the DOM. Or restore filtering with `<StyleSheetManager shouldForwardProp={...}>`.
 - Two classes per element: one shared across all instances of a component, one unique per style variant. Test selectors should account for both.
 - Stylis v4 parses `:hover {}` as descendant `& :hover {}`, not `&:hover {}`. Always write `&:hover`, `&::before`, etc.

sections/advanced/components-as-selectors.mdx

@@ -59,7 +59,7 @@ consider both sets of rules to understand why Icon behaves as it does.
 
 ### Caveat
 
-This behaviour is only supported within the context of _Styled_ Components:
+This behavior is only supported within the context of _Styled_ Components:
 interpolating `A` in the following example will trigger a development warning because component
 `A` is not a Styled Component.