adobe · devongovett · Jul 11, 2025 · Jun 27, 2025 · Jul 8, 2025 · Jul 8, 2025
diff --git a/.chromatic/preview-head.html b/.chromatic/preview-head.html
@@ -138,8 +138,7 @@
 <!--
   Load S2 adobe clean VF
 -->
-<link rel="preload" href="https://use.typekit.net/af/5e77d8/00000000000000007754d3a5/30/l?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=n1&v=3" as="font" crossorigin="anonymous" />
-<link rel="stylesheet" href="https://use.typekit.net/yuq6kxz.css">
+<link rel="preload" href="https://use.typekit.net/af/b1226a/0000000000000000775c0485/31/l?primer=f592e0a4b9356877842506ce344308576437e4f677d7c9b78ca2162e6cad991a&fvd=n1&v=3" as="font" crossorigin="anonymous" />
 
 <!--
   This web project loads adobe clean, adobe clean serif, myriad-arabic, myriad-hebrew, adobe-clean-han-japanese,

diff --git a/.storybook-s2/docs/Intro.jsx b/.storybook-s2/docs/Intro.jsx
@@ -140,41 +140,64 @@ export function Docs() {
         <P>You may also need to configure other tools such as TypeScript, Babel, ESLint, and Jest to support parsing import attributes. See <Link href="https://parceljs.org/features/macros/#usage-with-other-tools" target="_blank">these docs</Link> for details.</P>
         <P>See the <Link href="https://github.com/adobe/react-spectrum/tree/main/examples" target="_blank">examples folder</Link> in our repo for working setups with various build tools. For details on optimizing the output CSS, see the <Link href="?path=/docs/style-macro--docs#css-optimization" target="_top">style macro docs</Link>.</P>
         <H2>Setting up your app</H2>
-        <P>Unlike React Spectrum v3, a <Code>Provider</Code> is not required. Instead, import <Code>@react-spectrum/s2/page.css</Code> in the entry component of your app to apply the background color and color scheme to the <Code>{'<html>'}</Code> element. This ensures that the entire page has the proper styles even before your JavaScript runs.</P>
-        <Pre>{highlight(`import '@react-spectrum/s2/page.css';
-import {Button} from '@react-spectrum/s2';
+        <P>Wrap your app in an S2 <Code>{'<Provider>'}</Code> component to load Spectrum 2 fonts for the user's locale and apply the appropriate Spectrum background layer for your app. When using S2 together with other versions of Spectrum, ensure that the S2 provider is the inner-most provider.</P>
+        <Pre>{highlight(`import {Provider, Button} from '@react-spectrum/s2';
 
 function App() {
   return (
-    <Button
-      variant="accent"
-      onPress={() => alert('Hey there!')}>
-      Hello Spectrum 2!
-    </Button>
+    // Wrap app in a <Provider> to load fonts, set background, set locale, etc.
+    <Provider background="base">
+      <Button
+        variant="accent"
+        onPress={() => alert('Hey there!')}>
+        Hello Spectrum 2!
+      </Button>
+    </Provider>
   );
 }`)}</Pre>
         <Example>
           <Button variant="accent" onPress={() => alert('Hey there!')}>Hello Spectrum 2!</Button>
         </Example>
-        <P><Strong>Note</Strong>: If you’re embedding Spectrum 2 as a section of a larger page rather than taking over the whole window, follow the <Link href="#embedded-sections" target="_self">directions below</Link> instead of using <Code>page.css</Code>.</P>
+        <H3>Optimizing full-page apps</H3>
+        <P>When building a full page S2 app that's not embedded within a larger page, import <Code>@react-spectrum/s2/page.css</Code> to apply the background color and color scheme to the <Code>{'<html>'}</Code> element instead of the <Code>{'<Provider>'}</Code>. This ensures that the page has styles even before your JavaScript loads. A <Code>{'<Provider>'}</Code> is still necessary in addition to <Code>page.css</Code> in order to include the fonts, set the locale, etc.</P>
+        <Pre>{highlight(`// Apply S2 background to the <html> element
+import '@react-spectrum/s2/page.css';
+
+function App() {
+  return (
+    <Provider>
+      {/* ... */}
+    </Provider>
+  );
+}`)}</Pre>
+        <P>By default, this uses the <Code>base</Code> background layer. This can be customized by setting the <Code>data-background</Code> attribute on the <Code>{'<html>'}</Code> element.</P>
+        <Pre>{highlight(`<html data-background="layer-1">
+  <!-- ... -->
+</html>`)}</Pre>
         <H3>Overriding the color scheme</H3>
-        <P>By default, the page follows the user’s operating system color scheme setting, supporting both light and dark mode. The page background is set to the <Code>base</Code> Spectrum background layer by default. This can be configured by setting the <Code>data-color-scheme</Code> and <Code>data-background</Code> attributes on the <Code>{'<html>'}</Code> element. For example, to force the application to only render in light mode, set <Code>data-color-scheme="light"</Code>.</P>
+        <P>By default, React Spectrum follows the operating system color scheme setting, supporting both light and dark mode. The <Code>colorScheme</Code> prop can be set on <Code>{'<Provider>'}</Code> to force the app to always render in a certain color scheme.</P>
+        <Pre>{highlight(`import {Provider} from '@react-spectrum/s2';
+
+<Provider colorScheme="light">
+  {/* your app */}
+</Provider>`)}</Pre>
+        <P>When using <Code>page.css</Code>, set the <Code>data-color-scheme</Code> attribute on the <Code>{'<html>'}</Code> element.</P>
         <Pre>{highlight(`<html data-color-scheme="light">
   <!-- ... -->
 </html>`)}</Pre>
         <H3>Overriding the locale</H3>
-        <P>By default, React Spectrum uses the browser/operating system language setting for localized strings, date and number formatting, and to determine the layout direction (left-to-right or right-to-left). This can be overridden by rendering a <Code>{'<Provider>'}</Code> component at the root of your app, and setting the <Code>locale</Code> prop.</P>
+        <P>By default, React Spectrum uses the browser/operating system language setting for localized strings, date and number formatting, and to determine the layout direction (left-to-right or right-to-left). This can be overridden by rendering setting the <Code>locale</Code> prop on the <Code>{'<Provider>'}</Code>.</P>
         <Pre>{highlight(`import {Provider} from '@react-spectrum/s2';
 
 <Provider locale="en-US">
   {/* your app */}
 </Provider>`)}</Pre>
-        <H3>Embedded sections</H3>
-        <P>If you’re building an embedded section of a larger page using Spectrum 2, use the <Code>{'<Provider>'}</Code> component to set the background instead of importing <Code>page.css</Code>. The <Code>background</Code> prop should be set to the Spectrum background layer appropriate for your app, and the <Code>colorScheme</Code> can be overridden as well.</P>
-        <Pre>{highlight(`import {Provider} from '@react-spectrum/s2';
-
-<Provider background="base">
-  {/* your app */}
+        <H3>Server-side rendering</H3>
+        <P>When using SSR, the <Code>{'<Provider>'}</Code> component can be rendered as the root <Code>{'<html>'}</Code> element. The <Code>locale</Code> prop should always be specified to avoid hydration errors. <Code>page.css</Code> is not needed in this case.</P>
+        <Pre>{highlight(`<Provider elementType="html" locale="en-US">
+  <body>
+    {/* ... */}
+  </body>
 </Provider>`)}</Pre>
         <H3>Usage with older React Spectrum versions</H3>
         <P>See Adobe internal documentation.</P>

diff --git a/.storybook-s2/preview-head.html b/.storybook-s2/preview-head.html
@@ -1,24 +0,0 @@
-<!--
-  This web project loads adobe clean, adobe clean serif, myriad-arabic, myriad-hebrew, adobe-clean-han-japanese,
-  adobe-clean-han-korean, adobe-clean-han-simplified-c, and adobe-clean-han-traditional.
-  These fonts and this web project are managed by a team account.
--->
-<script>
-(function(d) {
-  var config = {
-    kitId: 'fqj0dxc',
-    scriptTimeout: 3000,
-    async: true
-  },
-  h=d.documentElement,t=setTimeout(function(){h.className=h.className.replace(/\bwf-loading\b/g,"")+" wf-inactive";},config.scriptTimeout),tk=d.createElement("script"),f=false,s=d.getElementsByTagName("script")[0],a;h.className+=" wf-loading";tk.src='https://use.typekit.net/'+config.kitId+'.js';tk.async=true;tk.onload=tk.onreadystatechange=function(){a=this.readyState;if(f||a&&a!="complete"&&a!="loaded")return;f=true;clearTimeout(t);try{Typekit.load(config)}catch(e){}};s.parentNode.insertBefore(tk,s)
-})(document);
-</script>
-<style>
-@font-face {
-    font-family: "Source Code Pro";
-    src: url("https://use.typekit.net/af/398a64/00000000000000007735dc06/30/l?primer=7cdcb44be4a7db8877ffa5c0007b8dd865b3bbc383831fe2ea177f62257a9191&fvd=n4&v=3") format("woff2"),url("https://use.typekit.net/af/398a64/00000000000000007735dc06/30/d?primer=7cdcb44be4a7db8877ffa5c0007b8dd865b3bbc383831fe2ea177f62257a9191&fvd=n4&v=3") format("woff"),url("https://use.typekit.net/af/398a64/00000000000000007735dc06/30/a?primer=7cdcb44be4a7db8877ffa5c0007b8dd865b3bbc383831fe2ea177f62257a9191&fvd=n4&v=3") format("opentype");
-    font-display: swap;
-    font-style: normal;
-    font-weight: 400;
-}
-</style>

diff --git a/packages/@react-spectrum/s2/chromatic/Fonts.stories.tsx b/packages/@react-spectrum/s2/chromatic/Fonts.stories.tsx
@@ -0,0 +1,198 @@
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import type {Meta} from '@storybook/react';
+import {style} from '../style' with {type: 'macro'};
+import {useLocale} from 'react-aria';
+
+const meta: Meta<any> = {
+  title: 'S2 Chromatic/Fonts'
+};
+
+export default meta;
+
+const messages = {
+  'en': {
+    'button': 'Edit',
+    'copy': 'Copy',
+    'cut': 'Cut',
+    'paste': 'Paste'
+  },
+  'ar': {
+    'button': 'يحرر',
+    'copy': 'ينسخ',
+    'cut': 'يقطع',
+    'paste': 'معجون'
+  },
+  'he': {
+    'button': 'לַעֲרוֹך',
+    'copy': 'עותק',
+    'cut': 'גזירה',
+    'paste': 'לְהַדבִּיק'
+  },
+  'ja': {
+    'button': '編集',
+    'copy': 'コピー',
+    'cut': '切る',
+    'paste': 'ペースト'
+  },
+  'ko': {
+    'button': '편집하다',
+    'copy': '복사',
+    'cut': '자르다',
+    'paste': '반죽'
+  },
+  'zh-Hans': {
+    'button': '编辑',
+    'copy': '复制',
+    'cut': '切',
+    'paste': '粘贴'
+  },
+  'zh-HK': {
+    'button': '編輯',
+    'copy': '複製',
+    'cut': '切',
+    'paste': '粘貼'
+  },
+  'zh-Hant': {
+    'button': '編輯',
+    'copy': '複製',
+    'cut': '切',
+    'paste': '粘貼'
+  }
+};
+
+function Example() {
+  let {locale} = useLocale();
+  let m = messages[locale] || messages.en;
+  return (
+    <div
+      className={style({
+        display: 'grid',
+        width: 'full',
+        gridTemplateColumns: {
+          default: '1fr',
+          sm: 'repeat(3, auto)',
+          md: 'repeat(6, auto)'
+        },
+        justifyContent: 'space-between'
+      })}>
+      <ul className={style({padding: 0, listStyleType: 'none'})}>
+        <li className={style({font: 'ui-xs'})}>{m.button}</li>
+        <li className={style({font: 'ui-sm'})}>{m.button}</li>
+        <li className={style({font: 'ui'})}>{m.button}</li>
+        <li className={style({font: 'ui-lg'})}>{m.button}</li>
+        <li className={style({font: 'ui-xl'})}>{m.button}</li>
+        <li className={style({font: 'ui-2xl'})}>{m.button}</li>
+        <li className={style({font: 'ui-3xl'})}>{m.button}</li>
+      </ul>
+      <ul className={style({padding: 0, listStyleType: 'none'})}>
+        <li className={style({font: 'body-2xs'})}>{m.copy}</li>
+        <li className={style({font: 'body-xs'})}>{m.copy}</li>
+        <li className={style({font: 'body-sm'})}>{m.copy}</li>
+        <li className={style({font: 'body'})}>{m.copy}</li>
+        <li className={style({font: 'body-lg'})}>{m.copy}</li>
+        <li className={style({font: 'body-xl'})}>{m.copy}</li>
+        <li className={style({font: 'body-2xl'})}>{m.copy}</li>
+        <li className={style({font: 'body-3xl'})}>{m.copy}</li>
+      </ul>
+      <ul className={style({padding: 0, listStyleType: 'none'})}>
+        <li className={style({font: 'heading-2xs'})}>{m.cut}</li>
+        <li className={style({font: 'heading-xs'})}>{m.cut}</li>
+        <li className={style({font: 'heading-sm'})}>{m.cut}</li>
+        <li className={style({font: 'heading'})}>{m.cut}</li>
+        <li className={style({font: 'heading-lg'})}>{m.cut}</li>
+        <li className={style({font: 'heading-xl'})}>{m.cut}</li>
+        <li className={style({font: 'heading-2xl'})}>{m.cut}</li>
+        <li className={style({font: 'heading-3xl'})}>{m.cut}</li>
+      </ul>
+      <ul className={style({padding: 0, listStyleType: 'none'})}>
+        <li className={style({font: 'title-xs'})}>{m.paste}</li>
+        <li className={style({font: 'title-sm'})}>{m.paste}</li>
+        <li className={style({font: 'title'})}>{m.paste}</li>
+        <li className={style({font: 'title-lg'})}>{m.paste}</li>
+        <li className={style({font: 'title-xl'})}>{m.paste}</li>
+        <li className={style({font: 'title-2xl'})}>{m.paste}</li>
+        <li className={style({font: 'title-3xl'})}>{m.paste}</li>
+      </ul>
+      <ul className={style({padding: 0, listStyleType: 'none'})}>
+        <li className={style({font: 'detail-sm'})}>{m.button}</li>
+        <li className={style({font: 'detail'})}>{m.button}</li>
+        <li className={style({font: 'detail-lg'})}>{m.button}</li>
+        <li className={style({font: 'detail-xl'})}>{m.button}</li>
+      </ul>
+      <ul className={style({padding: 0, listStyleType: 'none'})}>
+        <li className={style({font: 'code-sm'})}>{m.cut}</li>
+        <li className={style({font: 'code'})}>{m.cut}</li>
+        <li className={style({font: 'code-lg'})}>{m.cut}</li>
+        <li className={style({font: 'code-xl'})}>{m.cut}</li>
+      </ul>
+    </div>
+  );
+}
+
+function SerifExample() {
+  return (
+    <div
+      className={style({
+        display: 'grid',
+        width: 'full',
+        gridTemplateColumns: {
+          default: '1fr',
+          sm: 'repeat(3, auto)',
+          md: 'repeat(6, auto)'
+        },
+        justifyContent: 'space-between'
+      })}>
+      <ul className={style({padding: 0, listStyleType: 'none'})}>
+        <li className={style({font: 'heading-xs', fontFamily: 'serif'})}>Heading</li>
+        <li className={style({font: 'heading-sm', fontFamily: 'serif'})}>Heading</li>
+        <li className={style({font: 'heading', fontFamily: 'serif'})}>Heading</li>
+        <li className={style({font: 'heading-lg', fontFamily: 'serif'})}>Heading</li>
+        <li className={style({font: 'heading-xl', fontFamily: 'serif'})}>Heading</li>
+        <li className={style({font: 'heading-2xl', fontFamily: 'serif'})}>Heading</li>
+        <li className={style({font: 'heading-3xl', fontFamily: 'serif'})}>Heading</li>
+      </ul>
+      <ul className={style({padding: 0, listStyleType: 'none'})}>
+        <li className={style({font: 'body-2xs', fontFamily: 'serif'})}>Body</li>
+        <li className={style({font: 'body-xs', fontFamily: 'serif'})}>Body</li>
+        <li className={style({font: 'body-sm', fontFamily: 'serif'})}>Body</li>
+        <li className={style({font: 'body', fontFamily: 'serif'})}>Body</li>
+        <li className={style({font: 'body-lg', fontFamily: 'serif'})}>Body</li>
+        <li className={style({font: 'body-xl', fontFamily: 'serif'})}>Body</li>
+        <li className={style({font: 'body-2xl', fontFamily: 'serif'})}>Body</li>
+        <li className={style({font: 'body-3xl', fontFamily: 'serif'})}>Body</li>
+      </ul>
+    </div>
+  );
+}
+
+export const Default = {
+  render: () => <Example />,
+  parameters: {
+    chromaticProvider: {
+      colorSchemes: ['light'],
+      locales: ['en', 'ar', 'he', 'ja', 'ko', 'zh-Hans', 'zh-HK', 'zh-Hant']
+    }
+  }
+};
+
+export const Serif = {
+  render: () => <SerifExample />,
+  parameters: {
+    chromaticProvider: {
+      colorSchemes: ['light'],
+      // Only en because other locales don't have a serif font.
+      locales: ['en']
+    }
+  }
+};
diff --git a/packages/@react-spectrum/s2/src/CoachMark.tsx b/packages/@react-spectrum/s2/src/CoachMark.tsx
@@ -243,7 +243,6 @@ let description = style({
 let keyboard = style({
   gridArea: 'keyboard',
   font: 'ui',
-  fontWeight: 'light',
   color: 'gray-600',
   background: 'gray-25',
   unicodeBidi: 'plaintext'