docs: improve typography section, syntax

Author: rise-erpelding

1st-gen/tools/styles/README.md

@@ -26,39 +26,39 @@ See the `@spectrum-web-components/theme` [documentation](../theme) for more info
 yarn add @spectrum-web-components/styles
 ```
 
-## System variants
+### System variants
 
 This package provides styles for three Adobe design system variants (referred to as "systems"). Each system has different available color options:
 
-- **Spectrum Legacy** (system: `spectrum`) - The original Spectrum design system with four color options: `dark`, `light`, and deprecated `darkest` and `lightest`
+- **Spectrum** (system: `spectrum`) - The original Spectrum design system with four color options: `dark`, `light`, and deprecated `darkest` and `lightest`
 - **Express** (system: `express`) - The Adobe Express design system with two color options: `dark` and `light`
 - **Spectrum 2** (system: `spectrum-two`) - The next generation Spectrum design system with two color options: `dark` and `light`
 
-## Combined theme packages (Spectrum Legacy)
+### Combined theme packages (Spectrum)
 
-If you're not using `<sp-theme>`, the styles package provides convenience bundles for Spectrum Legacy that combine everything you need in a single import. Each `all-*` file combines core global styles, typography, a color option, and a scale specification. Express and Spectrum 2 do not have equivalent combined packages; use manual theme composition instead (see below).
+If you're not using `<sp-theme>`, the styles package provides convenient bundles for Spectrum that combine everything you need in a single import. Each `all-*` file combines core global styles, typography, a color option, and a scale specification. Express and Spectrum 2 do not have equivalent combined packages; use manual theme composition instead (see below).
 
 > **Note:** The `darkest` and `lightest` colors are deprecated and will be removed in a future release. Use `dark` or `light` instead.
 
-```ts
+```css
 @import '@spectrum-web-components/styles/all-medium-dark.css';
 ```
 
 This file brings together the global variables and font settings with the "Dark" color set and "Medium" scale system specification.
 
-```ts
+```css
 @import '@spectrum-web-components/styles/all-medium-light.css';
 ```
 
 This file brings together the global variables and font settings with the "Light" color set and "Medium" scale system specification.
 
 Other available combinations: `all-large-dark.css`, `all-large-light.css`, and the deprecated `all-medium-darkest.css`, `all-medium-lightest.css`, `all-large-darkest.css`, `all-large-lightest.css`.
 
-## Manual theme composition (Express and Spectrum 2)
+### Manual theme composition (Express and Spectrum 2)
 
-If you're not using `<sp-theme>`, you can manually compose a complete theme for Express or Spectrum 2 (equivalent to the `all-*` convenience packages for Spectrum Legacy) by importing four files: core global styles, typography, a color option, and a scale.
+If you're not using `<sp-theme>`, you can manually compose a complete theme for Express or Spectrum 2 (equivalent to the `all-*` convenience packages for Spectrum) by importing four files: core global styles, typography, a color option, and a scale.
 
-**Express example (large, dark):**
+#### Express example (large, dark)
 
 ```css
 @import '@spectrum-web-components/styles/express/core-global.css';
@@ -67,7 +67,7 @@ If you're not using `<sp-theme>`, you can manually compose a complete theme for
 @import '@spectrum-web-components/styles/express/scale-large.css';
 ```
 
-**Spectrum 2 example (medium, light):**
+#### Spectrum 2 example (medium, light)
 
 ```css
 @import '@spectrum-web-components/styles/spectrum-two/core-global.css';
@@ -78,16 +78,16 @@ If you're not using `<sp-theme>`, you can manually compose a complete theme for
 
 > **Note:** For most use cases, we recommend using `<sp-theme>` instead of manually managing these imports. The theme element handles composition and switching automatically.
 
-## Individual theme and scale files
+### Individual theme and scale files
 
 For more control over bundle size or to manually compose themes, you can import color and scale files individually. These provide only the CSS custom properties specific to color or scale, without the combined overhead of the `all-*` packages.
 
-### Color
+#### Color
 
 Import a single color option to set color values:
 
 ```css
-/* Spectrum Legacy */
+/* Spectrum */
 @import '@spectrum-web-components/styles/theme-light.css';
 
 /* Express */
@@ -97,7 +97,7 @@ Import a single color option to set color values:
 @import '@spectrum-web-components/styles/spectrum-two/theme-light.css';
 ```
 
-**Available color options:**
+##### Available color options
 
 <sp-table>
     <sp-table-head>
@@ -106,7 +106,7 @@ Import a single color option to set color values:
     </sp-table-head>
     <sp-table-body>
         <sp-table-row>
-            <sp-table-cell><strong>Spectrum Legacy</strong></sp-table-cell>
+            <sp-table-cell><strong>Spectrum</strong></sp-table-cell>
             <sp-table-cell><code>theme-dark.css</code>, <code>theme-light.css</code>, <code>theme-darkest.css</code> (deprecated), <code>theme-lightest.css</code> (deprecated)</sp-table-cell>
         </sp-table-row>
         <sp-table-row>
@@ -122,12 +122,12 @@ Import a single color option to set color values:
 
 > **Note:** All color theme files automatically set the CSS `color-scheme` property (`light` or `dark`) for accessibility. This helps browsers render native form controls appropriately, adjusts scrollbar colors to match the theme, and improves compatibility with system UI elements.
 
-### Scale
+#### Scale
 
 Import a single scale to set sizing values:
 
 ```css
-/* Spectrum Legacy */
+/* Spectrum */
 @import '@spectrum-web-components/styles/scale-medium.css';
 
 /* Express */
@@ -137,7 +137,7 @@ Import a single scale to set sizing values:
 @import '@spectrum-web-components/styles/spectrum-two/scale-large.css';
 ```
 
-**Available scales:**
+##### Available scales
 
 <sp-table>
     <sp-table-head>
@@ -146,7 +146,7 @@ Import a single scale to set sizing values:
     </sp-table-head>
     <sp-table-body>
         <sp-table-row>
-            <sp-table-cell><strong>Spectrum Legacy</strong></sp-table-cell>
+            <sp-table-cell><strong>Spectrum</strong></sp-table-cell>
             <sp-table-cell><code>scale-medium.css</code>, <code>scale-large.css</code></sp-table-cell>
         </sp-table-row>
         <sp-table-row>
@@ -160,15 +160,11 @@ Import a single scale to set sizing values:
     </sp-table-body>
 </sp-table>
 
-## Typography
-
-```ts
-@import '@spectrum-web-components/styles/typography.css';
-```
+### Typography
 
-This file provides the complete [Spectrum Typography system](https://opensource.adobe.com/spectrum-css/?path=/docs/components-typography--docs). The typography system is shared across all design systems (Spectrum Legacy, Express, and Spectrum 2).
+The [Spectrum Typography system](https://opensource.adobe.com/spectrum-css/?path=/docs/components-typography--docs) provides a complete set of text styles. The typography system is shared across all design systems (Spectrum, Express, and Spectrum 2).
 
-**What's included:**
+#### What's included
 
 - **Heading** styles (`.spectrum-Heading`) - Multiple sizes from XXS to XXXL with weight variants (light, regular, heavy) and serif options
 - **Body** styles (`.spectrum-Body`) - Multiple sizes from XS to XXXL with serif options for body copy and longer text
@@ -178,63 +174,80 @@ This file provides the complete [Spectrum Typography system](https://opensource.
 - **Emphasis and strong** - Proper italic and bold styling for `<em>` and `<strong>` elements within each typography class
 - **High contrast mode support** - Ensures text remains readable when Windows High Contrast Mode is enabled
 
-### TypeScript/JavaScript exports for Lit components
+#### CSS imports
+
+For stylesheet use, import the complete typography system:
+
+```css
+@import '@spectrum-web-components/styles/typography.css';
+```
+
+#### TypeScript/JavaScript exports for Lit components
+
+For use in Lit-based components, you can import typography styles as JavaScript modules. Import the complete system or individual components depending on your needs:
 
-For use in Lit-based components, you can import typography styles as JavaScript modules:
+##### Import everything
 
-```ts
+```js
 import typographyStyles from '@spectrum-web-components/styles/typography.js';
-import bodyStyles from '@spectrum-web-components/styles/body.js';
-import headingStyles from '@spectrum-web-components/styles/heading.js';
-import detailStyles from '@spectrum-web-components/styles/detail.js';
-import codeStyles from '@spectrum-web-components/styles/code.js';
 
-// Use in your component's static styles
 static styles = [typographyStyles];
 ```
 
-- **`typography.js`** - Complete typography system with all classes
-- **`body.js`** - Body text styles only (base + lang + body classes)
-- **`heading.js`** - Heading styles only (base + lang + heading classes)
-- **`detail.js`** - Detail/label styles only (base + lang + detail classes)
-- **`code.js`** - Code styles only (base + lang + code classes)
+##### Import only what you need
+
+For smaller bundle sizes, import individual components:
+
+```js
+import headingStyles from '@spectrum-web-components/styles/heading.js';
+
+static styles = [headingStyles];
+```
 
-Import individual exports when you only need specific typography components to reduce bundle size.
+##### Available JavaScript exports
 
-## Design tokens
+- **`typography.js`** - Complete typography system with all styles (heading, body, detail, code)
+- **`body.js`** - Body text styles only (includes base + lang + body)
+- **`heading.js`** - Heading styles only (includes base + lang + heading)
+- **`detail.js`** - Detail/label styles only (includes base + lang + detail)
+- **`code.js`** - Code styles only (includes base + lang + code)
+
+Each individual export (`body.js`, `heading.js`, etc.) includes the necessary base and language support styles, so you don't need to import them separately. Import `typography.js` for the complete system, or import individual exports to reduce bundle size.
+
+### Design tokens
 
 For advanced use cases where you need direct access to design token CSS custom properties, this package exposes token files:
 
-### Spectrum Legacy tokens
+#### Spectrum tokens
 
-```ts
+```css
 @import '@spectrum-web-components/styles/tokens/global-vars.css';
 @import '@spectrum-web-components/styles/tokens/light-vars.css';
 @import '@spectrum-web-components/styles/tokens/dark-vars.css';
 @import '@spectrum-web-components/styles/tokens/medium-vars.css';
 @import '@spectrum-web-components/styles/tokens/large-vars.css';
 ```
 
-### Express tokens
+#### Express tokens
 
-```ts
+```css
 @import '@spectrum-web-components/styles/tokens/express/global-vars.css';
 @import '@spectrum-web-components/styles/tokens/express/light-vars.css';
 @import '@spectrum-web-components/styles/tokens/express/dark-vars.css';
 @import '@spectrum-web-components/styles/tokens/express/medium-vars.css';
 @import '@spectrum-web-components/styles/tokens/express/large-vars.css';
 ```
 
-### Spectrum 2 tokens
+#### Spectrum 2 tokens
 
-```ts
+```css
 @import '@spectrum-web-components/styles/tokens-v2/global-vars.css';
 @import '@spectrum-web-components/styles/tokens-v2/light-vars.css';
 @import '@spectrum-web-components/styles/tokens-v2/dark-vars.css';
 @import '@spectrum-web-components/styles/tokens-v2/medium-vars.css';
 @import '@spectrum-web-components/styles/tokens-v2/large-vars.css';
 ```
 
-## Migrating to Spectrum 2
+### Migrating to Spectrum 2
 
 If you're migrating to Spectrum 2, see the [Spectrum 2 migration guide](../../migrating-to-spectrum2/) for detailed instructions.