docs(v7): native CanIUse + v7 docs pulled up to latest styled-components (#1005)

* docs(v7): pull latest native polyfills into matrix, native.mdx, llms.txt

New v7 surface reflected across the compatibility matrix and v7 docs:
accent-color, overscroll-behavior, scrollbar-width, text-overflow,
direction → writingDirection, font-size keyword parity, letter-spacing
font-relative units, CSS Color 4 system-color fold inside box-shadow /
filter / background / linear-gradient stops, animation-composition
longhand, :nth-child(<an+b> of S), styled.ScrollView flex-shrink: 0
default, border-radius slash form, border-style hidden / mixed handling.

Fixes verified against react-native 0.85.2: aspect-ratio slash form
actually works natively without v7; mix-blend-mode iOS count is 15
non-normal modes, not 16.

AGENTS.md gains rules: matrix entries describe author-facing behavior
not internals (public RN prop names allowed); public docs strip
mechanism; American English in all prose.

* docs(v7): rn-web parity follow-ups

- object-fit: rn-web Image now picks up the CSS property via resizeMode
- styled.ScrollView flex-shrink: 0 baseline applies on native only;
  rn-web keeps the default so scrolling works

* docs(v7): drop mechanism narration from public-facing prose

Trim polyfill mechanism (lifts X, polyfills by Y, attaches Z) out of
matrix summaries and v7 docs. Keep what's supported, what isn't, what
to author. Affected entries: accent-color, overscroll-behavior,
scrollbar-width, text-overflow, direction, object-fit, line-clamp,
background-blend-mode, interactivity, caret-color, ScrollView baseline.

* docs(v7): pull custom properties, !important, font-size units, rn-web bundle

CSS custom properties cascade through styled components on native: declare
`--name: value` and descendants read it back via `var(--name, fallback)`.
References resolve inside every conditional bucket (`@media`, `@container`,
attribute, pseudo-state, `:has()`, `:nth-child()`, combinator).

`!important` is honored within a component for base + every conditional
bucket, flows through `var()` substitution and render-time resolvers, and
beats a runtime `style={{ ... }}` prop. Ignored inside `@keyframes` per
spec. Cross-component cascade is not yet supported.

`font-size` accepts the full unit catalogue: viewport units, container
query units, font-relative, font-metric approximations, and absolute
lengths.

`styled-components/native` now ships a dedicated build for `react-native-web`
consumers, auto-detected by Webpack / Vite / Metro web targets.

* chore: AGENTS.md prose sweep and small cleanups

Replaced em-dashes across docs prose with colons, semicolons, periods,
or parentheses per the project rule. Dropped the literal em-dash glyph
from the blog byline divider in favor of a middle dot.

Fixed three Nav components that pixel sizes through `rem()`; nav and
sidebar widths use plain px from `utils/sizes.ts`.

`utils/blog.server.ts` now loads MDX modules concurrently via
`Promise.all`. `utils/cssCompatFormats.ts` deduplicates a double sort.
`Nav/SidebarMenus.tsx` hoists `activeHref(pathname)` out of its top-level
`.map` so the lookup runs once per render instead of per item.

Removed two unused exports: `searchModalWidth` in `utils/sizes.ts`
and the precomputed `Author.websiteHost` in `utils/authors.ts`.

* docs(v7): address Copilot review on PR #1005

- text-overflow: make the required companion line limit explicit
  (sections/v7/native.mdx, public/llms.txt, utils/cssCompat.ts).
  RN's ellipsizeMode is a no-op without numberOfLines, so authors
  need line-clamp or text-wrap: nowrap alongside text-overflow.
- overscroll-behavior: drop `chain` from the summary. It is not a
  valid CSS keyword; the spec only accepts auto | contain | none.
- border-radius: downgrade v6, iosStock, androidStock to `partial`
  to reflect that only v7 accepts the slash-separated CSS grammar
  (when circular). Stock RN has no per-axis radius surface.
- AGENTS.md: remove the contradiction between the public-docs rule
  and the matrix exception. Matrix follows the same no-mechanism
  rule, with one narrow exception for naming a public stock-RN
  prop when explaining version skew.

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: quantizor

AGENTS.md

@@ -49,3 +49,11 @@ Gotchas (things you cannot discover by reading the code alone)
 - Blog posts are assembled at build time by `utils/blog.server.ts` from MDX `meta` exports. No JSON index.
 - Blog Bluesky comments are opt-in via `blueskyPostUrl` in MDX `meta`. Auto-discovery is intentionally disabled (Bluesky closed public `searchPosts`). `BlogComments.tsx` overrides hashed CSS-Module selectors via `[class*='_name_']` matches so overrides survive package upgrades.
 - CSS compatibility matrix (`utils/cssCompat.ts`) v6/v7 columns describe combined-platform native behavior. If iOS stock = yes but Android stock = no, v7 should be `partial`, not `no`. `prUrls` is keyed per column; only set entries where status is `no` and an upstream PR exists.
+- Public-facing docs (`sections/`, `public/llms.txt`, blog posts) describe user-observable behavior only: what is supported, what isn't, what to author. Skip mechanism (how the polyfill maps, what prop it lifts, internal field names, parser / handler / registry mechanics, ABI prefixes, dev-warn IDs, sentinel names).
+- The compatibility matrix (`utils/cssCompat.ts`) follows the same no-mechanism rule, with one narrow exception: when explaining version skew, an entry may name a public stock-RN prop (`numberOfLines`, `trackColor`) instead of the CSS-side surface, because the matrix exists to compare authoring across versions. Everything else (parser, handler, registry, ABI prefixes, dev-warn IDs, sentinel names) is still off-limits, and caveats are gotchas the author needs to act on, not internals.
+
+Prose rules (mirrored from `~/code/styled-components/AGENTS.md`)
+- American English in all prose: color, behavior, honor, recognize, serialize, center, organize, etc. Keep original spelling only inside verbatim quotes.
+- Avoid em-dashes. Use the full family of punctuation marks (colon, semicolon, parentheses, period).
+- Don't paste CSS spec normative text into consumer-facing docs. Link to the relevant `drafts.csswg.org` section and summarize user-observable behavior. Spec `§n.n` anchors and verbatim quotes belong next to test assertions, not in prose docs (this includes the compatibility matrix).
+- Don't name specific AI coding assistants. "An AI coding assistant" is the neutral phrasing.

components/BlogMeta.tsx

@@ -171,7 +171,7 @@ const JumpToComments = styled.a`
   }
 `;
 
-export const BlogDivider = styled.span.attrs({ 'aria-hidden': 'true', children: '—' })`
+export const BlogDivider = styled.span.attrs({ 'aria-hidden': 'true', children: '·' })`
   color: ${theme.color.blogAccentMuted};
 `;
 

components/Nav/MobileNavbar.tsx

@@ -1,6 +1,5 @@
 import styled, { css } from 'styled-components';
 import { mobile } from '../../utils/media';
-import rem from '../../utils/rem';
 import { navbarHeight } from '../../utils/sizes';
 import { theme } from '../../utils/theme';
 import Link from '../Link';
@@ -28,7 +27,7 @@ export default function MobileNavbar({ isSideFolded, onSideToggle }: MobileNavba
         {isSideFolded ? <FoldIcon /> : <CloseIcon />}
       </NavButton>
 
-      <LogoLink href="/">
+      <LogoLink>
         <Logo />
       </LogoLink>
 
@@ -44,7 +43,7 @@ const Wrapper = styled.div`
     align-items: center;
     display: flex;
     flex-grow: 1;
-    height: ${rem(navbarHeight)};
+    height: ${navbarHeight}px;
     justify-content: space-between;
     padding-left: calc(${theme.layout.gutter} - ${NAV_BUTTON_ICON_INSET}px);
     padding-right: calc(${theme.layout.gutter} - ${THEME_TOGGLE_ICON_INSET}px);

components/Nav/NavButton.tsx

@@ -16,7 +16,7 @@ const NavButton = styled.button.attrs(() => ({
   background: transparent;
   cursor: pointer;
   flex: 0 0 auto;
-  height: ${rem(navbarHeight)};
+  height: ${navbarHeight}px;
   padding: 0 ${rem(10)};
   text-align: center;
   transition: all 200ms ease-in-out;

components/Nav/SidebarMenus.tsx

@@ -95,6 +95,7 @@ export default function SidebarMenu({ latestPost }: { latestPost: LatestPost })
     [currentDocsPage]
   );
   const activeId = useScrollSpy(sectionIds);
+  const currentActiveHref = activeHref(pathname);
 
   return (
     <MenuRoot aria-label="Site navigation">
@@ -103,7 +104,7 @@ export default function SidebarMenu({ latestPost }: { latestPost: LatestPost })
       </SearchWrapper>
 
       {TOP_LEVEL.map(({ href, label, icon: Icon, external, badge, badgeTone }) => {
-        const isActive = !external && href === activeHref(pathname);
+        const isActive = !external && href === currentActiveHref;
 
         return (
           <TopSection key={href}>

components/Nav/Social.tsx

@@ -14,7 +14,7 @@ const Wrapper = styled.nav.attrs({ 'aria-label': 'Social links' })`
 const SocialLink = styled(Link).attrs({ variant: 'unstyled' as const })`
   display: flex;
   margin-right: ${rem(20)};
-  line-height: ${rem(navbarHeight)};
+  line-height: ${navbarHeight}px;
   transition:
     opacity 0.2s,
     transform 0.2s;